vsrepo 2.6.0 → 2.7.1

package/CHANGELOG.md

@@ -6,6 +6,48 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [2.7.1] - 2026-09-28
+
+### Fixed
+- A dynamic method now resolves every parameter by its own position instead of relying on the end of the argument list — the `options` are read from the first argument after the expected parameters, and the payload (`data`/`create`/`update`), `order` and `pagination` of a method called with more than one extra argument are now read from the correct slots instead of shifting onto the `options` object. Arguments beyond the expected parameters plus `options` are ignored
+- A failing dynamic method is no longer logged at `ERROR` by the resolver — the error is simply rethrown to the caller and the execution time is still recorded by `endPerformLog`, leaving `ERROR` for validation and guard-clause failures. This is the last call site that still logged it: the base methods, `query()` and the query methods had already stopped in **2.0.0**
+
+### Documentation
+- Both logging guides now describe `ERROR` accurately: it is logged for validation and guard-clause failures right before the `VSRepoError` is thrown, while a failure raised by the adapter itself is no longer logged and simply propagates to the caller
+
+## [2.7.1] - 2026-09-28 (Português)
+
+### Corrigido
+- Um método dinâmico agora resolve cada parâmetro pela sua própria posição em vez de depender do fim da lista de argumentos — as `options` são lidas do primeiro argumento depois dos parâmetros esperados, e o payload (`data`/`create`/`update`), o `order` e a `pagination` de um método chamado com mais de um argumento extra passam a ser lidos dos slots corretos, em vez de deslocarem para o objeto de options. Argumentos além dos parâmetros esperados mais as options são ignorados
+- Um método dinâmico que falha não é mais logado em `ERROR` pelo resolver — o erro simplesmente é relançado para quem chamou e o tempo de execução continua sendo registrado por `endPerformLog`, deixando o `ERROR` para falhas de validação e de guarda. Esta é a última chamada que ainda registrava o erro: os métodos base, o `query()` e os query methods já haviam parado na **2.0.0**
+
+### Documentação
+- Os dois guias de logging agora descrevem o `ERROR` com precisão: ele é registrado para falhas de validação e de guarda logo antes do `VSRepoError` ser lançado, enquanto uma falha lançada pelo próprio adapter não é mais registrada e simplesmente propaga para quem chamou
+
+## [2.7.0] - 2026-09-26
+
+### Added
+- **`createRawQueryBuilder(db?)`** — new method on every `VSRepository` that returns a fluent, SQL-agnostic `VSRawQueryBuilder` for hand-written `SELECT` queries too SQL-specific (window functions, vendor-specific syntax, ad-hoc subqueries, CTEs, ...) for `createQueryBuilder()`'s `where`/`relations` model. Chain `select`, `from`, `innerJoin`/`leftJoin`/`rightJoin`/`fullJoin`, `where`/`andWhere`/`orWhere`, `groupBy`, `having`/`andHaving`/`orHaving`, `orderBy`, `limit` and `offset` — each accepting either a raw, trusted string (an identifier, or a parameter-free condition for `on`/`where`/`having`, e.g. `.andWhere("deleted_at is null")`) or a `VSSql` fragment for anything parameterized. `from()`/joins also accept another `VSRawQueryBuilder`, or a subquery function (`sub => sub.select(...)...`) that receives a fresh builder sharing the same `db`/adapter/logger, compiled inline as a subquery; any subquery can also be spliced directly into a `VSSql` fragment via `toVSSql()` (e.g. inside a `WHERE ... IN (...)`). `with(name, query, columns?)`/`withRecursive(name, query, columns?)` add named CTEs (a single `WITH RECURSIVE` clause once any CTE is recursive) that the rest of the query can reference like real tables. Run it with `toVSSql()` (the compiled `VSSql` fragment), `toSql()` (the plain SQL string, rendered with the adapter's placeholder syntax) or `execute<T>()` (runs it through the adapter and returns the result); all three require the adapter to implement `getPlaceholder()`. The builder respects `clone()` and lazy `setDb()`, same as `createQueryBuilder()`, and is exported as `VSRawQueryBuilder`/`VSRawQueryBuilderTarget`/`VSRawQueryBuilderCteQuery`. Every raw string accepted as an identifier, condition, alias or CTE name/column is validated as non-empty/non-blank as soon as it's passed, throwing a `VSRepoError` instead of silently compiling into broken SQL
+- **`VSSql`** — ORM-agnostic, composable SQL fragments for raw queries: build one with `VSSql.sql` (a tagged template where every interpolated value becomes a bound parameter), `VSSql.raw` (inserts trusted, unparameterized text — for identifiers only, never user input), `VSSql.join` (builds a parameterized list, e.g. an `IN (...)`) and `VSSql.empty` (contributes no text/params, for conditional fragments). Fragments nest freely and the placeholder numbering stays correct; passing one to `VSRepository.query()` compiles it through `adapter.getPlaceholder()` — so `VSSql` works with every database and is safe from SQL injection by construction
+- **`vsPlaceholders`** constructor option — when `true`, raw SQL strings passed to `query()` and `@QueryMethod` use VSRepository's own agnostic, 1-based, positional placeholders (`?1`, `?2`, ...) instead of the adapter's native syntax; the same index can repeat (`?1 ... ?1`) to reuse an argument. Requires the adapter to implement `getPlaceholder()` — enabling it without one throws a `VSRepoError`
+- **`VSRepoAdapter.getPlaceholder?`** — new optional adapter method declaring the placeholder syntax for the Nth (0-based) bound parameter (e.g. `` `$${index + 1}` `` for PostgreSQL, `"?"` for SQLite/MySQL). Implementing it is what enables `VSSql` fragments and `vsPlaceholders`
+- **Query method logs** — `query()` and `@QueryMethod` now log the compiled query and its args at `DEBUG` (the `db` is never logged) and time the execution (`Took Xms ...`, promoted to `WARN` above `logSlowThresholdMs`), like the rest of the library
+
+### Documentation
+- New [Raw query builder](./docs/raw-query-builder.md) guide, covering `createRawQueryBuilder()`, building the query, subqueries (builder or function), CTEs with `with()`/`withRecursive()`, running it (`toVSSql`/`toSql`/`execute`), transactions/`setDb()`, cloning, validation and logs — added to both READMEs' documentation index, with a cross-link from the [Query builder](./docs/query-builder.md) guide
+
+## [2.7.0] - 2026-09-26 (Português)
+
+### Adicionado
+- **`createRawQueryBuilder(db?)`** — novo método em todo `VSRepository` que retorna um `VSRawQueryBuilder` fluente e agnóstico de SQL para queries `SELECT` escritas à mão, específicas demais (funções de janela, sintaxe específica do banco, subqueries ad-hoc, CTEs, ...) para o modelo `where`/`relations` do `createQueryBuilder()`. Encadeie `select`, `from`, `innerJoin`/`leftJoin`/`rightJoin`/`fullJoin`, `where`/`andWhere`/`orWhere`, `groupBy`, `having`/`andHaving`/`orHaving`, `orderBy`, `limit` e `offset` — cada um aceitando uma string crua e confiável (um identificador, ou uma condição sem parâmetros para `on`/`where`/`having`, ex.: `.andWhere("deleted_at is null")`) ou um fragmento `VSSql` para qualquer coisa parametrizada. `from()`/joins também aceitam outro `VSRawQueryBuilder`, ou uma função de subquery (`sub => sub.select(...)...`) que recebe um builder novo compartilhando o mesmo `db`/adapter/logger, compilada inline como subquery; qualquer subquery também pode ser inserida diretamente num fragmento `VSSql` via `toVSSql()` (ex.: dentro de um `WHERE ... IN (...)`). `with(name, query, columns?)`/`withRecursive(name, query, columns?)` adicionam CTEs nomeadas (uma única cláusula `WITH RECURSIVE` quando qualquer CTE é recursiva) que o resto da query pode referenciar como tabelas normais. Execute com `toVSSql()` (o fragmento `VSSql` compilado), `toSql()` (a string SQL simples, renderizada com a sintaxe de placeholder do adapter) ou `execute<T>()` (executa através do adapter e retorna o resultado); os três exigem que o adapter implemente `getPlaceholder()`. O builder respeita `clone()` e `setDb()` lazy, igual ao `createQueryBuilder()`, e é exportado como `VSRawQueryBuilder`/`VSRawQueryBuilderTarget`/`VSRawQueryBuilderCteQuery`. Toda string crua aceita como identificador, condição, alias ou nome/coluna de CTE é validada como não-vazia/não-em-branco assim que é passada, lançando um `VSRepoError` em vez de compilar silenciosamente em SQL quebrado
+- **`VSSql`** — fragmentos SQL agnósticos de ORM e componíveis para queries raw: monte um com `VSSql.sql` (um template literal com tag em que todo valor interpolado vira um parâmetro ligado), `VSSql.raw` (insere texto confiável e não parametrizado — só para identificadores, nunca input do usuário), `VSSql.join` (monta uma lista parametrizada, ex.: um `IN (...)`) e `VSSql.empty` (não contribui com texto nem parâmetros, para fragmentos condicionais). Fragmentos aninham livremente e a numeração dos placeholders continua correta; passar um para o `VSRepository.query()` compila via `adapter.getPlaceholder()` — então `VSSql` funciona com qualquer banco e é seguro contra SQL injection por construção
+- **Option `vsPlaceholders`** no construtor — quando `true`, strings SQL cruas passadas para `query()` e `@QueryMethod` usam os placeholders próprios, agnósticos, posicionais e de base 1 do VSRepository (`?1`, `?2`, ...) em vez da sintaxe nativa do adapter; o mesmo índice pode se repetir (`?1 ... ?1`) para reutilizar um argumento. Exige que o adapter implemente `getPlaceholder()` — ligar essa option sem ele lança um `VSRepoError`
+- **`VSRepoAdapter.getPlaceholder?`** — novo método opcional no adapter que declara a sintaxe de placeholder para o N-ésimo (base 0) parâmetro ligado (ex.: `` `$${index + 1}` `` para o PostgreSQL, `"?"` para SQLite/MySQL). Implementá-lo é o que habilita os fragmentos `VSSql` e o `vsPlaceholders`
+- **Logs dos métodos de query** — `query()` e `@QueryMethod` agora logam a query compilada e seus args em `DEBUG` (o `db` nunca é logado) e medem a execução (`Took Xms ...`, promovido para `WARN` acima do `logSlowThresholdMs`), como no resto da biblioteca
+
+### Documentação
+- Novo guia [Raw query builder](./docs/raw-query-builder.pt-BR.md), cobrindo o `createRawQueryBuilder()`, a construção da query, subqueries (builder ou função), CTEs com `with()`/`withRecursive()`, execução (`toVSSql`/`toSql`/`execute`), transações/`setDb()`, clonagem, validação e logs — adicionado ao índice de documentação dos dois READMEs, com um cross-link a partir do guia [Query builder](./docs/query-builder.pt-BR.md)
+
 ## [2.6.0] - 2026-09-24
 
 ### Added
@@ -14,7 +56,7 @@ All notable changes to this project will be documented in this file.
 - **`VSRepoErrorType.QUERY_BUILDER`** — new error type, thrown as a `VSRepoError` when an invalid argument is passed to a query builder method
 - **Query builder logs** — the builder uses the repository's logger: at `DEBUG` it traces every chained call and the resolved query of each terminal method (the `db` is never logged), and each terminal method is timed (`Took Xms to run query builder <method>`, promoted to `WARN` above `logSlowThresholdMs`)
 - **`Equals` / `NotEquals`** field-filter suffixes for dynamic methods — same effect as no suffix and `Not`, respectively; useful to disambiguate a field name that ends at the same camelCase boundary as an existing keyword suffix (e.g. `findByCheckInEquals` resolves to the field `checkIn`, instead of the default `check` + `In` reading)
-- **`lazyDynamicMethods`** constructor option — when `true`, postpones resolving `@DynamicMethod`/`@QueryMethod` methods until the subclass calls the `protected resolveDynamicMethods()` itself, instead of resolving them synchronously in the constructor. Useful for deferring the resolution cost to a more convenient point in the app's lifecycle (e.g. an async init hook), and lets fields annotated with `@DynamicMethod`/`@QueryMethod` skip the `declare` modifier as long as `resolveDynamicMethods()` is called after calls `supper()`. Calling `resolveDynamicMethods()` again after it already resolved once logs a `WARN`, since it's redundant
+- **`lazyDynamicMethods`** constructor option — when `true`, postpones resolving `@DynamicMethod`/`@QueryMethod` methods until the subclass calls the `protected resolveDynamicMethods()` itself, instead of resolving them synchronously in the constructor. Useful for deferring the resolution cost to a more convenient point in the app's lifecycle (e.g. an async init hook), and lets fields annotated with `@DynamicMethod`/`@QueryMethod` skip the `declare` modifier as long as `resolveDynamicMethods()` is called after calls `super()`. Calling `resolveDynamicMethods()` again after it already resolved once logs a `WARN`, since it's redundant
 
 ### Changed
 - `pagination` validation is now stricter: `limit` and `offset` must be non-negative integers. Negative, decimal and infinite values, previously accepted, are now rejected
@@ -254,7 +296,7 @@ All notable changes to this project will be documented in this file.
 
 ## [2.0.0] - 2026-09-01
  
-> Major rewrite. If you're upgrading from v1, see the ["What changed from v1"](./README.md#what-changed-from-v1) table in the README for the full breakdown before migrating.
+> Major rewrite. If you're upgrading from v1, see the [Migrating from v1](./docs/migrating-from-v1.md) guide for the full breakdown before migrating.
  
 ### Changed
 - **BREAKING:** VSRepository is now **ORM-agnostic** — the core no longer talks to Prisma directly, it delegates every operation to a pluggable `VSRepoAdapter`. ORM support now ships as separate packages (e.g. `@vsrepo/prisma7-adapter`) instead of being bundled in the core `vsrepo` package
@@ -291,7 +333,7 @@ All notable changes to this project will be documented in this file.
  
 ## [2.0.0] - 2026-09-01 (Português)
  
-> Reescrita major. Se você está migrando da v1, veja a tabela ["O que mudou da v1"](./README.pt-BR.md#o-que-mudou-da-v1) no README para o detalhamento completo antes de migrar.
+> Reescrita major. Se você está migrando da v1, veja o guia [Migrando da v1](./docs/migrating-from-v1.pt-BR.md) para o detalhamento completo antes de migrar.
  
 ### Alterado
 - **BREAKING:** O VSRepository agora é **agnóstico de ORM** — o core não conversa mais diretamente com o Prisma, delegando toda operação a um `VSRepoAdapter` plugável. O suporte a ORMs agora é publicado em pacotes separados (ex.: `@vsrepo/prisma7-adapter`) em vez de vir embutido no pacote core `vsrepo`

package/README.md

@@ -13,63 +13,21 @@
 
 🇺🇸 You're reading the English version. [🇧🇷 Ler em português](./README.pt-BR.md)
 
-**ORM-agnostic** repository pattern library, with full **TypeScript** support and automatic **type inference**. The core delegates every operation to a pluggable **adapter**, so the same repository API can work against Prisma, Drizzle, or any other ORM/database that implements the adapter contract. Coming from the old [v1](https://github.com/jaobrabo123/VSRepository/tree/v1)? See [Migrating from v1](./docs/migrating-from-v1.md).
+VSRepository is an **ORM-agnostic repository pattern library for TypeScript**. It provides a consistent repository API, derived query methods, query builders, transactions, and other persistence concerns through pluggable **ORM adapters**.
 
 VSRepository lets you create strongly-typed repositories with:
 
 - Automatic **base methods**: `get`, `getOrThrow`, `getList`, `save`, `saveList`, `remove`, `removeList`, `patch`, `merge`, `getAll`, `total`, `has`
 - **Native soft-delete**: `softRemove`, `softRemoveList`, `restore`, `restoreList`
 - **Dynamic methods** inferred from a `declare` field name via the `@DynamicMethod` decorator: `findOneByEmail`, `findByStatusPaginated`, `updateById`
-- **Raw SQL query methods** via the `@QueryMethod` decorator, bypassing the name-parsing engine entirely
-- Ad-hoc **`select`/`relations`** per call — no more pre-declared named projections
-- **Type safety** across 100% of operations
+- **Raw SQL query methods** via the `@QueryMethod` decorator (bypassing the name-parsing engine entirely), parameterized `VSSql` fragments for ad-hoc `query()` calls, and agnostic `?1`, `?2` placeholders with `vsPlaceholders`
+- Ad-hoc **`select`/`relations`** per call
+- Strong **TypeScript** typing across the repository API
 - Native ORM **transactions**, shared across repositories
 - An **ORM-agnostic core** — the same repository class works with any `VSRepoAdapter` implementation
 
 ---
 
-## Documentation
-
-The sections below (adapter status, installation, basic usage) are the essentials to get you started. Everything about a specific feature — with more detail and more examples — lives in its own guide under [`docs/`](./docs/README.md), each available in English and in [Português](./docs/README.pt-BR.md):
-
-| Guide | Covers |
-| --- | --- |
-| [Base methods, configuration & soft-delete](./docs/base-methods.md) | Constructor options, the 12 automatic CRUD methods, native soft-delete, and the 8 atomic/aggregate methods (`increment`, `sum`, ...). |
-| [`select` and `relations`](./docs/select-and-relations.md) | Ad-hoc field selection and eager relation loading on any call, and `InferMethodReturn` to narrow the return type accordingly. |
-| [Dynamic methods](./docs/dynamic-methods.md) | `findByEmail`-style methods parsed from a `declare`d method name: prefixes, field filters, logical operators, relation filters, ordering/pagination/distinct. |
-| [Query methods (raw SQL)](./docs/query-methods.md) | Raw SQL methods via `@QueryMethod`, bypassing the dynamic-method name parser entirely. |
-| [Query builder](./docs/query-builder.md) | The fluent `createQueryBuilder()` API for queries assembled at runtime, including pagination, soft-delete visibility and transactions. |
-| [Transactions](./docs/transactions.md) | Running several repositories against the same native ORM transaction. |
-| [Utility types](./docs/utility-types.md) | The exported helper types (`InferMethodType`, `InferMethodReturn`, `KeysOfType`, ...) and where each one is used. |
-| [Writing your own adapter](./docs/writing-an-adapter.md) | How to implement `VSRepoAdapter` for a new ORM or database, method by method. |
-| [Error handling](./docs/error-handling.md) | `VSRepoError`, `VSRepoErrorType`, and `VSRepoAdapterError`/`AdapterErrorCode`. |
-| [Logging](./docs/logging.md) | `logLevel`, `logSlowThresholdMs`, and the log format used by the repository and the query builder. |
-| [Migrating from v1](./docs/migrating-from-v1.md) | Everything that changed between v1 and v2 — API, config, renamed suffixes, removed features — in a single reference for migrating existing repositories. |
-
----
-
-## Adapter status
-
-VSRepository is **ORM-agnostic by design**. The core package (`vsrepo`) only ships the repository class, the decorators, the name-parsing engine, error handling and logging — it does **not** ship a production adapter. Actual ORM/database support is meant to live in **separate, independently versioned packages**, one per ORM (and, where it makes sense, one per major ORM version), for example:
-
-- `@vsrepo/prisma7-adapter`
-- `@vsrepo/prisma8-adapter`
-- `@vsrepo/typeorm-adapter`
-- `@vsrepo/drizzle-adapter`
-
-The Prisma 7 adapter is published to npm as `@vsrepo/prisma7-adapter`. The Drizzle adapter is available as an **alpha** release — install it with `@vsrepo/drizzle-adapter@alpha`. Adapters for other ORMs are **planned** but not published yet. Until an official `@vsrepo/*-adapter` package exists for your ORM, you're welcome to write your own for your project, and if you'd like, publish it and open a PR to help grow the ecosystem — contributions here are very welcome.
-
-| Adapter                              | Status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Prisma 7 (`@vsrepo/prisma7-adapter`) | 🟢 **Released** — published to npm, implements the `VSRepoAdapter` contract (CRUD, relations, transactions, `merge`, logging, etc.) with tests; see [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) for source and docs. |
-| Drizzle (`@vsrepo/drizzle-adapter`)  | 🔵 **Alpha** — an early release is available on npm; install it with `npm i @vsrepo/drizzle-adapter@alpha`. The API may still change before the stable release. Check the [`DrizzleAdapter`](https://github.com/jaobrabo123/VSRepoDrizzleAdapter) repository for the current status and known limitations, and feel free to contribute.                                                                                                                                                                                                                                                                                                         |
-| Other ORMs (Prisma 8, TypeORM, etc.) | 🟡 **Planned, not published yet.** No official package exists yet — write your own adapter for now (see [Writing your own adapter](./docs/writing-an-adapter.md#writing-your-own-adapter)), and consider publishing/contributing it back.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Custom adapters                      | 🟢 Fully supported today — implement the [`VSRepoAdapter`](./docs/writing-an-adapter.md#writing-your-own-adapter) abstract class yourself for any ORM/database you need, in your own project or package.                                                                                                                                                                                                                                                                                                                                                                                               |
-
-In short: the repository class, the `@DynamicMethod`/`@QueryMethod` decorators, the name-parsing engine, error handling and logging are all working end-to-end, and Prisma 7 support is a released, published adapter. The Drizzle adapter is available in alpha. Official adapters for the remaining ORMs are on the roadmap and will ship as separate `@vsrepo/*-adapter` packages rather than as part of the core `vsrepo` package — but you don't have to wait for that: writing (and optionally publishing) your own adapter in the meantime is a fully supported way to use VSRepository today and to contribute back to the project.
-
----
-
 ## Installation
 
 VSRepository is installed as the core package plus one adapter package for your ORM, for example:
@@ -82,26 +40,12 @@ npm i vsrepo @vsrepo/prisma7-adapter
 
 ## Basic usage
 
-### Implementing/choosing an adapter
-
-```typescript
-// src/configs/db.ts
-import { PrismaClient } from "../../generated/prisma/client";
-import { PrismaPg } from "@prisma/adapter-pg";
-import "dotenv/config";
-
-const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
-const prisma = new PrismaClient({ adapter });
-
-export default prisma;
-```
-
 ### Creating a repository
 
 ```typescript
 // src/repositories/user.repository.ts
 import { VSRepository, DynamicMethod } from "vsrepo";
-import { VSRepoPrisma7Adapter } from "@vsrepo/prisma7-adapter";
+import { Prisma7Adapter } from "@vsrepo/prisma7-adapter";
 import prisma from "../configs/db";
 import type { UserGetPayload } from "../../generated/prisma/models";
 
@@ -110,8 +54,7 @@ type User = UserGetPayload<{ include: { address: true } }>;
 class UserRepository extends VSRepository<User, string> {
     constructor() {
         super({
-            pkName: "id",
-            adapter: new VSRepoPrisma7Adapter<User>(prisma, { tableName: "user", pkName: "id" }),
+            adapter: new Prisma7Adapter(prisma, { tableName: "user", pkName: "id" }),
             softRemoveKey: "deletedAt",
             defaultOrdering: { createdAt: "desc" },
         });
@@ -129,20 +72,6 @@ export default new UserRepository();
 
 > The core API (`VSRepository`, `VSRepoAdapter`, `DynamicMethod`, `QueryMethod`, `VSRepoError`, enums and types) is imported from the single `vsrepo` entry point. The concrete adapter comes from a **separate** package (`@vsrepo/*-adapter`). On Prisma 7, install the [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter).
 
-> **The third generic parameter (`OrmTypes`):** `VSRepository<Entity, PKType, OrmTypes>` accepts an optional third type parameter describing your ORM's client/transaction types, via `VSRepoOrmTypes` (`{ dbClient; dbTransaction }`). Supplying it gives you a correctly-typed `getDbClient()`, `transaction()` callback, and `db` option on every method, instead of `any`:
->
-> ```typescript
-> import { Prisma7OrmTypes } from "@vsrepo/prisma7-adapter";
-> 
-> type MyOrmTypes = Prisma7OrmTypes<PrismaClient>;
->
-> class UserRepository extends VSRepository<User, string, MyOrmTypes> {
->     // getDbClient() now returns PrismaClient, and transaction(fn) types `tx` as Prisma.TransactionClient
-> }
-> ```
->
-> If omitted, it defaults to `VSRepoOrmTypes` (`dbClient`/`dbTransaction` both `any`).
-
 ### Using the repository
 
 ```typescript
@@ -164,29 +93,43 @@ await userRepository.remove(user.id);
 
 ---
 
-## Development
-
-```bash
-# 1. Install dependencies
-bun install
+## Documentation
 
-# 2. Compile the TypeScript sources into dist/ (removes a previous dist/ first)
-bun run build
+The sections above (installation, basic usage) are the essentials to get you started. Everything about a specific feature — with more detail and more examples — lives in its own guide under [`docs/`](./docs/README.md), each available in English and in [Português](./docs/README.pt-BR.md):
+
+### Guides
+
+| Guide                                                               | Covers                                                                                                                                                                |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Adapter status](./docs/adapters.md)                                | Which ORM adapters exist today, what "ORM-agnostic by design" means in practice, and how to install, write or publish your own.                                       |
+| [Base methods, configuration & soft-delete](./docs/base-methods.md) | Constructor options, the 12 automatic CRUD methods, native soft-delete, and the 8 atomic/aggregate methods (`increment`, `sum`, ...).                                 |
+| [`select` and `relations`](./docs/select-and-relations.md)          | Ad-hoc field selection and eager relation loading on any call, and `InferMethodReturn` to narrow the return type accordingly.                                         |
+| [Dynamic methods](./docs/dynamic-methods.md)                        | `findByEmail`-style methods parsed from a `declare`d method name: prefixes, field filters, logical operators, relation filters, ordering/pagination/distinct.         |
+| [Query methods (raw SQL)](./docs/query-methods.md)                  | Raw SQL via `@QueryMethod`, parameterized `VSSql` fragments and the agnostic `?1`/`?2` placeholders (`vsPlaceholders`).                                               |
+| [Query builder](./docs/query-builder.md)                            | The fluent `createQueryBuilder()` API for queries assembled at runtime, including pagination, soft-delete visibility and transactions.                                |
+| [Raw query builder](./docs/raw-query-builder.md)                    | The fluent `createRawQueryBuilder()` API for hand-written `SELECT` queries too SQL-specific for the query builder — joins, subqueries, CTEs (`with`/`withRecursive`). |
+| [Transactions](./docs/transactions.md)                              | Running several repositories against the same native ORM transaction.                                                                                                 |
+| [Utility types](./docs/utility-types.md)                            | The exported helper types (`InferMethodType`, `InferMethodReturn`, `KeysOfType`, ...) and where each one is used.                                                     |
+| [Writing your own adapter](./docs/writing-an-adapter.md)            | What an adapter is responsible for, and how to implement the `VSRepoAdapter` contract for a new ORM or database.                                                      |
+| [Error handling](./docs/error-handling.md)                          | `VSRepoError`, `VSRepoErrorType`, and `VSRepoAdapterError`/`AdapterErrorCode`.                                                                                        |
+| [Logging](./docs/logging.md)                                        | `logLevel`, `logSlowThresholdMs`, and the log format used by the repository and the query builder.                                                                    |
+| [Contributing](./CONTRIBUTING.md)                                   | Repository layout, the key scripts, conventions and CI — plus the contribution flow itself (issues, pull requests, review).                                           |
+| [Migrating from v1](./docs/migrating-from-v1.md)                    | Everything that changed between v1 and v2 — API, config, renamed suffixes, removed features — in a single reference for migrating existing repositories.              |
 
-# 3. (Optional) Inspect what would be published without writing a tarball
-npm pack --dry-run
+---
 
-# 4. Produce the installable tarball (runs `prepack` -> `bun run build` automatically)
-npm pack
+## Adapter status
 
-# 5. Consume it locally in another project
-npm install ../path/to/vsrepo-*.tgz
-```
+VSRepository is **ORM-agnostic by design**: the core package (`vsrepo`) ships only the repository class, the decorators, the name-parsing engine, error handling and logging — no production adapter. ORM support lives in separate, independently versioned `@vsrepo/*-adapter` packages, so each one can follow its own ORM's release cycle.
 
-Notes:
+| Adapter                              | Status                                                                                                                                       |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Prisma 7 (`@vsrepo/prisma7-adapter`) | 🟢 **Released** — published to npm, with tests. [Source and docs](https://github.com/jaobrabo123/VSRepoPrisma7Adapter).                      |
+| Drizzle (`@vsrepo/drizzle-adapter`)  | 🔵 **Alpha** — `npm i @vsrepo/drizzle-adapter@alpha`. The API may still change. [Repo](https://github.com/jaobrabo123/VSRepoDrizzleAdapter). |
+| Other ORMs (Prisma 8, TypeORM, etc.) | 🟡 **Planned, not published yet.** Write your own in the meantime — it's fully supported.                                                    |
+| Custom adapters                      | 🟢 Fully supported — implement `VSRepoAdapter` yourself, in your own project or package.                                                     |
 
-- `bun run build` runs `tsc -p tsconfig.build.json`, which outputs the compiled JS and generated type declarations into `dist/` with `rootDir: src`.
-- The published package contains **only** the `dist/` folder, the READMEs, `CHANGELOG.md` and `LICENSE` (see `files` in `package.json`). The adapters will live in their own `@vsrepo/*-adapter` packages.
+The full status and how to install each one: [Adapter status](./docs/adapters.md). To publish your own, see [Publishing your own adapter](./docs/writing-an-adapter.md#publishing-your-own-adapter).
 
 ---
 
@@ -204,17 +147,12 @@ Notes:
 ```
 
 - `reflect-metadata` (bundled as a dependency, imported internally — you don't need to import it yourself)
-- At least one working `VSRepoAdapter` for your database — on Prisma 7, install the published [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) (see [Adapter status](#adapter-status)); official adapters for other ORMs are planned but not published yet, so for now this means writing your own (see [Writing your own adapter](./docs/writing-an-adapter.md#writing-your-own-adapter)) — and if you publish it, contributing it back to the project is welcome
+- At least one working `VSRepoAdapter` for your database — on Prisma 7, install the published [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) (see [Adapter status](#adapter-status))
 
 ---
 
 ## Contributing
 
-Contributions are welcome, especially for improving the Prisma adapter and finishing the Drizzle one! (**[GitHub repository](https://github.com/jaobrabo123/VSRepository)**):
-
-1. **Fork** the project.
-2. Create a branch for your change: `git checkout -b my-change`.
-3. Push your branch: `git push origin my-change`.
-4. Open a **Pull Request**.
+Contributions are welcome — adapters, bug reports and documentation alike. The core is ORM-agnostic, so ORM-specific work belongs in your own adapter package; see the scope rules before opening a PR.
 
-To report issues or suggest features, open an **Issue**.
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — how to report a bug, request a feature, and submit a pull request.

package/README.pt-BR.md

@@ -13,63 +13,21 @@
 
 🇧🇷 Você está lendo a versão em português. [🇺🇸 Read in English](./README.md)
 
-Biblioteca de repository pattern **agnóstica de ORM**, com suporte completo a **TypeScript** e **type inference** automático. O núcleo delega toda operação a um **adapter** plugável, permitindo que a mesma API de repository funcione com Prisma, Drizzle ou qualquer outro ORM/banco que implemente o contrato de adapter. Vindo da [v1](https://github.com/jaobrabo123/VSRepository/tree/v1)? Veja [Migrando da v1](./docs/migrating-from-v1.pt-BR.md).
+O VSRepository é uma **biblioteca de repository pattern agnóstica de ORM para TypeScript**. Ela fornece uma API de repository consistente, métodos de consulta derivados, query builders, transações e outros recursos relacionados à persistência por meio de **adapters de ORM plugáveis**.
 
 O VSRepository permite criar repositories fortemente tipados com:
 
 - **Métodos base** automáticos: `get`, `getOrThrow`, `getList`, `save`, `saveList`, `remove`, `removeList`, `patch`, `merge`, `getAll`, `total`, `has`
 - **Soft-delete nativo**: `softRemove`, `softRemoveList`, `restore`, `restoreList`
 - **Métodos dinâmicos** inferidos a partir do nome de um campo `declare` via o decorador `@DynamicMethod`: `findOneByEmail`, `findByStatusPaginated`, `updateById`
-- **Métodos de query SQL raw** através do decorador `@QueryMethod`, ignorando totalmente o engine de parsing por nome
-- **`select`/`relations`** ad-hoc em cada chamada — sem mais projeções nomeadas pré-declaradas
-- **Type safety** em 100% das operações
+- **Métodos de query SQL raw** através do decorador `@QueryMethod` (ignorando totalmente o engine de parsing por nome), fragmentos parametrizados `VSSql` para chamadas pontuais de `query()`, e placeholders agnósticos `?1`, `?2` com `vsPlaceholders`
+- **`select`/`relations`** ad-hoc em cada chamada
+- Tipagem forte com **TypeScript** em toda a API do repositório
 - **Transações** nativas do ORM, compartilhadas entre repositories
 - Um **núcleo agnóstico de ORM** — a mesma classe de repository funciona com qualquer implementação de `VSRepoAdapter`
 
 ---
 
-## Documentação
-
-As seções abaixo (status dos adapters, instalação, uso básico) são o essencial para começar. Tudo sobre uma funcionalidade específica — com mais detalhe e mais exemplos — vive em um guia próprio dentro de [`docs/`](./docs/README.pt-BR.md), cada um disponível em português e em [English](./docs/README.md):
-
-| Guia | Cobre |
-| --- | --- |
-| [Métodos base, configuração & soft-delete](./docs/base-methods.pt-BR.md) | Options do construtor, os 12 métodos CRUD automáticos, soft-delete nativo, e os 8 métodos atômicos/de agregação (`increment`, `sum`, ...). |
-| [`select` e `relations`](./docs/select-and-relations.pt-BR.md) | Seleção de campos e carregamento de relações ad-hoc em qualquer chamada, e o `InferMethodReturn` para estreitar o tipo de retorno de acordo. |
-| [Métodos dinâmicos](./docs/dynamic-methods.pt-BR.md) | Métodos no estilo `findByEmail`, resolvidos a partir de um nome de método `declare`d: prefixos, filtros de campo, operadores lógicos, filtros de relação, ordenação/paginação/distinct. |
-| [Query methods (SQL raw)](./docs/query-methods.pt-BR.md) | Métodos de SQL raw via `@QueryMethod`, ignorando totalmente o parser de nomes dos métodos dinâmicos. |
-| [Query builder](./docs/query-builder.pt-BR.md) | A API fluente `createQueryBuilder()` para queries montadas em tempo de execução, incluindo paginação, visibilidade de soft-delete e transações. |
-| [Transações](./docs/transactions.pt-BR.md) | Rodando vários repositories na mesma transação nativa do ORM. |
-| [Tipos utilitários](./docs/utility-types.pt-BR.md) | Os tipos utilitários exportados (`InferMethodType`, `InferMethodReturn`, `KeysOfType`, ...) e onde cada um é usado. |
-| [Escrevendo seu próprio adapter](./docs/writing-an-adapter.pt-BR.md) | Como implementar o `VSRepoAdapter` para um novo ORM ou banco, método a método. |
-| [Tratamento de erros](./docs/error-handling.pt-BR.md) | `VSRepoError`, `VSRepoErrorType`, e `VSRepoAdapterError`/`AdapterErrorCode`. |
-| [Logging](./docs/logging.pt-BR.md) | `logLevel`, `logSlowThresholdMs`, e o formato de log usado pelo repository e pelo query builder. |
-| [Migrando da v1](./docs/migrating-from-v1.pt-BR.md) | Tudo o que mudou entre a v1 e a v2 — API, config, sufixos renomeados, funcionalidades removidas — em uma única referência para migrar repositories existentes. |
-
----
-
-## Status dos adapters
-
-O VSRepository é **agnóstico de ORM por design**. O pacote core (`vsrepo`) traz apenas a classe de repository, os decoradores, o engine de parsing de nomes, o tratamento de erros e o logging — ele **não** inclui um adapter de produção. O suporte de fato a cada ORM/banco deve viver em **pacotes separados, versionados de forma independente**, um por ORM (e, quando fizer sentido, um por versão principal do ORM), por exemplo:
-
-- `@vsrepo/prisma7-adapter`
-- `@vsrepo/prisma8-adapter`
-- `@vsrepo/typeorm-adapter`
-- `@vsrepo/drizzle-adapter`
-
-O adapter do Prisma 7 já foi publicado no npm como `@vsrepo/prisma7-adapter`. O adapter do Drizzle está disponível em versão **alpha** — instale com `npm i @vsrepo/drizzle-adapter@alpha`. Os adapters para outros ORMs estão **planejados**, mas ainda não foram publicados. Até que exista um pacote `@vsrepo/*-adapter` oficial para o seu ORM, você pode escrever o seu próprio para o seu projeto e, se quiser, publicá-lo e abrir um PR para ajudar a fazer o ecossistema crescer — contribuições nesse sentido são muito bem-vindas.
-
-| Adapter                               | Status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Prisma 7 (`@vsrepo/prisma7-adapter`)  | 🟢 **Lançado** — publicado no npm, implementa o contrato de `VSRepoAdapter` (CRUD, relations, transactions, `merge`, logging, etc.) com testes; veja o [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) para o código-fonte e docs. |
-| Drizzle (`@vsrepo/drizzle-adapter`)   | 🔵 **Alpha** — uma versão inicial já está disponível no npm; instale com `npm i @vsrepo/drizzle-adapter@alpha`. A API ainda pode mudar antes do release estável. Veja o repositório do [`DrizzleAdapter`](https://github.com/jaobrabo123/VSRepoDrizzleAdapter) para o estado atual e limitações conhecidas, e sinta-se à vontade para contribuir.                                                                                                                                                                                                                                                                                                                                                       |
-| Outros ORMs (Prisma 8, TypeORM, etc.) | 🟡 **Planejados, ainda não publicados.** Nenhum pacote oficial existe ainda — por enquanto, escreva o seu próprio adapter (veja [Escrevendo seu próprio adapter](./docs/writing-an-adapter.pt-BR.md#escrevendo-seu-próprio-adapter)) e considere publicá-lo/contribuir de volta com o projeto.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Adapters customizados                 | 🟢 Totalmente suportados hoje — implemente você mesmo a classe abstrata [`VSRepoAdapter`](./docs/writing-an-adapter.pt-BR.md#escrevendo-seu-próprio-adapter) para qualquer ORM/banco que precisar, no seu próprio projeto ou pacote.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-
-Resumindo: a classe de repository, os decoradores `@DynamicMethod`/`@QueryMethod`, o engine de parsing de nomes, o tratamento de erros e o logging já funcionam de ponta a ponta, e o suporte ao Prisma 7 é um adapter lançado e publicado. O adapter do Drizzle está disponível em alpha. Adapters oficiais para os demais ORMs estão no roadmap e serão distribuídos como pacotes `@vsrepo/*-adapter` separados, e não como parte do pacote core `vsrepo` — mas você não precisa esperar por isso: escrever (e opcionalmente publicar) o seu próprio adapter enquanto isso é uma forma totalmente suportada de usar o VSRepository hoje e de contribuir de volta com o projeto.
-
----
-
 ## Instalação
 
 O VSRepository é instalado como o pacote core mais um pacote de adapter para o seu ORM, por exemplo:
@@ -82,26 +40,12 @@ npm i vsrepo @vsrepo/prisma7-adapter
 
 ## Uso básico
 
-### Implementando/escolhendo um adapter
-
-```typescript
-// src/configs/db.ts
-import { PrismaClient } from "../../generated/prisma/client";
-import { PrismaPg } from "@prisma/adapter-pg";
-import "dotenv/config";
-
-const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
-const prisma = new PrismaClient({ adapter });
-
-export default prisma;
-```
-
 ### Criando um repository
 
 ```typescript
 // src/repositories/user.repository.ts
 import { VSRepository, DynamicMethod } from "vsrepo";
-import { VSRepoPrisma7Adapter } from "@vsrepo/prisma7-adapter";
+import { Prisma7Adapter } from "@vsrepo/prisma7-adapter";
 import prisma from "../configs/db";
 import type { UserGetPayload } from "../../generated/prisma/models";
 
@@ -110,8 +54,7 @@ type User = UserGetPayload<{ include: { address: true } }>;
 class UserRepository extends VSRepository<User, string> {
     constructor() {
         super({
-            pkName: "id",
-            adapter: new VSRepoPrisma7Adapter<User>(prisma, { tableName: "user", pkName: "id" }),
+            adapter: new Prisma7Adapter(prisma, { tableName: "user", pkName: "id" }),
             softRemoveKey: "deletedAt",
             defaultOrdering: { createdAt: "desc" },
         });
@@ -129,20 +72,6 @@ export default new UserRepository();
 
 > A API do core (`VSRepository`, `VSRepoAdapter`, `DynamicMethod`, `QueryMethod`, `VSRepoError`, enums e tipos) é importada do entry point único `vsrepo`. O adapter concreto vem de um pacote **separado** (`@vsrepo/*-adapter`). No Prisma 7, instale o [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter).
 
-> **O terceiro generic (`OrmTypes`):** `VSRepository<Entity, PKType, OrmTypes>` aceita um terceiro type parameter opcional descrevendo os tipos de client/transaction do seu ORM, via `VSRepoOrmTypes` (`{ dbClient; dbTransaction }`). Ao fornecê-lo, `getDbClient()`, o callback de `transaction()` e a option `db` de todo método passam a ser tipados corretamente, em vez de `any`:
->
-> ```typescript
-> import { Prisma7OrmTypes } from "@vsrepo/prisma7-adapter";
-> 
-> type MyOrmTypes = Prisma7OrmTypes<PrismaClient>;
->
-> class UserRepository extends VSRepository<User, string, MyOrmTypes> {
->     // getDbClient() agora retorna PrismaClient, e transaction(fn) tipa `tx` como Prisma.TransactionClient
-> }
-> ```
->
-> Se omitido, o padrão é `VSRepoOrmTypes` (`dbClient`/`dbTransaction` como `any`).
-
 ### Usando o repository
 
 ```typescript
@@ -164,29 +93,43 @@ await userRepository.remove(usuario.id);
 
 ---
 
-## Desenvolvimento
-
-```bash
-# 1. Instalar as dependências
-bun install
+## Documentação
 
-# 2. Compilar os fontes TypeScript em dist/ (remove um dist/ anterior primeiro)
-bun run build
+As seções acima (instalação, uso básico) são o essencial para começar. Tudo sobre uma funcionalidade específica — com mais detalhe e mais exemplos — vive em um guia próprio dentro de [`docs/`](./docs/README.pt-BR.md), cada um disponível em português e em [English](./docs/README.md):
+
+### Guias
+
+| Guia                                                                     | Cobre                                                                                                                                                                                   |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Status dos adapters](./docs/adapters.pt-BR.md)                          | Quais adapters de ORM existem hoje, o que "agnóstico de ORM por design" significa na prática, e como instalar, escrever ou publicar o seu.                                              |
+| [Métodos base, configuração & soft-delete](./docs/base-methods.pt-BR.md) | Options do construtor, os 12 métodos CRUD automáticos, soft-delete nativo, e os 8 métodos atômicos/de agregação (`increment`, `sum`, ...).                                              |
+| [`select` e `relations`](./docs/select-and-relations.pt-BR.md)           | Seleção de campos e carregamento de relações ad-hoc em qualquer chamada, e o `InferMethodReturn` para estreitar o tipo de retorno de acordo.                                            |
+| [Métodos dinâmicos](./docs/dynamic-methods.pt-BR.md)                     | Métodos no estilo `findByEmail`, resolvidos a partir de um nome de método `declare`d: prefixos, filtros de campo, operadores lógicos, filtros de relação, ordenação/paginação/distinct. |
+| [Query methods (SQL raw)](./docs/query-methods.pt-BR.md)                 | SQL raw via `@QueryMethod`, fragmentos parametrizados `VSSql` e os placeholders agnósticos `?1`/`?2` (`vsPlaceholders`).                                                                |
+| [Query builder](./docs/query-builder.pt-BR.md)                           | A API fluente `createQueryBuilder()` para queries montadas em tempo de execução, incluindo paginação, visibilidade de soft-delete e transações.                                         |
+| [Raw query builder](./docs/raw-query-builder.pt-BR.md)                   | A API fluente `createRawQueryBuilder()` para queries `SELECT` escritas à mão, específicas demais para o query builder — joins, subqueries, CTEs (`with`/`withRecursive`).               |
+| [Transações](./docs/transactions.pt-BR.md)                               | Rodando vários repositories na mesma transação nativa do ORM.                                                                                                                           |
+| [Tipos utilitários](./docs/utility-types.pt-BR.md)                       | Os tipos utilitários exportados (`InferMethodType`, `InferMethodReturn`, `KeysOfType`, ...) e onde cada um é usado.                                                                     |
+| [Escrevendo seu próprio adapter](./docs/writing-an-adapter.pt-BR.md)     | Do que um adapter é responsável, e como implementar o contrato `VSRepoAdapter` para um novo ORM ou banco.                                                                               |
+| [Tratamento de erros](./docs/error-handling.pt-BR.md)                    | `VSRepoError`, `VSRepoErrorType`, e `VSRepoAdapterError`/`AdapterErrorCode`.                                                                                                            |
+| [Logging](./docs/logging.pt-BR.md)                                       | `logLevel`, `logSlowThresholdMs`, e o formato de log usado pelo repository e pelo query builder.                                                                                        |
+| [Contribuindo](./CONTRIBUTING.pt-BR.md)                                  | Estrutura do repositório, os principais scripts, convenções e CI — mais o próprio fluxo de contribuição (issues, pull requests, revisão).                                               |
+| [Migrando da v1](./docs/migrating-from-v1.pt-BR.md)                      | Tudo o que mudou entre a v1 e a v2 — API, config, sufixos renomeados, funcionalidades removidas — em uma única referência para migrar repositories existentes.                          |
 
-# 3. (Opcional) Inspecionar o que seria publicado sem gerar um tarball
-npm pack --dry-run
+---
 
-# 4. Gerar o tarball instalável (roda `prepack` -> `bun run build` automaticamente)
-npm pack
+## Status dos adapters
 
-# 5. Consumir localmente em outro projeto
-npm install ../caminho/vsrepo-*.tgz
-```
+O VSRepository é **agnóstico de ORM por design**: o pacote core (`vsrepo`) traz apenas a classe de repository, os decoradores, o engine de parsing de nomes, o tratamento de erros e o logging — nenhum adapter de produção. O suporte a ORM vive em pacotes `@vsrepo/*-adapter` separados e versionados de forma independente, então cada um pode acompanhar o ciclo de releases do seu próprio ORM.
 
-Observações:
+| Adapter                               | Status                                                                                                                                            |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Prisma 7 (`@vsrepo/prisma7-adapter`)  | 🟢 **Lançado** — publicado no npm, com testes. [Código e docs](https://github.com/jaobrabo123/VSRepoPrisma7Adapter).                              |
+| Drizzle (`@vsrepo/drizzle-adapter`)   | 🔵 **Alpha** — `npm i @vsrepo/drizzle-adapter@alpha`. A API ainda pode mudar. [Repositório](https://github.com/jaobrabo123/VSRepoDrizzleAdapter). |
+| Outros ORMs (Prisma 8, TypeORM, etc.) | 🟡 **Planejados, ainda não publicados.** Escreva o seu enquanto isso — é totalmente suportado.                                                    |
+| Adapters customizados                 | 🟢 Totalmente suportados — implemente o `VSRepoAdapter` você mesmo, no seu projeto ou pacote.                                                     |
 
-- `bun run build` executa `tsc -p tsconfig.build.json`, que gera o JS compilado e as declarações de tipo em `dist/` com `rootDir: src`.
-- O pacote publicado contém **apenas** a pasta `dist/`, os READMEs, o `CHANGELOG.md` e a `LICENSE` (veja `files` no `package.json`). Os adapters viverão em seus próprios pacotes `@vsrepo/*-adapter`.
+O status completo e como instalar cada um: [Status dos adapters](./docs/adapters.pt-BR.md). Para publicar o seu, veja [Publicando o seu próprio adapter](./docs/writing-an-adapter.pt-BR.md#publicando-o-seu-próprio-adapter).
 
 ---
 
@@ -204,17 +147,12 @@ Observações:
 ```
 
 - `reflect-metadata` (já incluso como dependência, importado internamente — você não precisa importá-lo você mesmo)
-- Pelo menos um `VSRepoAdapter` funcional para o seu banco — no Prisma 7, instale o [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) já publicado (veja [Status dos adapters](#status-dos-adapters)); adapters oficiais para outros ORMs estão planejados, mas ainda não publicados, então por enquanto isso significa escrever o seu próprio (veja [Escrevendo seu próprio adapter](./docs/writing-an-adapter.pt-BR.md#escrevendo-seu-próprio-adapter)) — e, se publicá-lo, contribuir de volta com o projeto é bem-vindo
+- Pelo menos um `VSRepoAdapter` funcional para o seu banco — no Prisma 7, instale o [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) já publicado (veja [Status dos adapters](#status-dos-adapters))
 
 ---
 
 ## Contribuindo
 
-Contribuições são bem-vindas, especialmente para melhorar o adapter do Prisma e finalizar o do Drizzle! (**[Repositório do GitHub](https://github.com/jaobrabo123/VSRepository)**):
-
-1. Faça um **Fork** do projeto.
-2. Crie uma branch para sua alteração: `git checkout -b minha-alteracao`.
-3. Faça o push da sua branch: `git push origin minha-alteracao`.
-4. Abra um **Pull Request**.
+Contribuições são bem-vindas — adapters, reports de bug e documentação. O core é agnóstico de ORM, então trabalho específico de ORM pertence ao seu próprio pacote de adapter; veja as regras de escopo antes de abrir um PR.
 
-Para reportar problemas ou sugerir funcionalidades, abra uma **Issue**.
+- **[CONTRIBUTING.pt-BR.md](./CONTRIBUTING.pt-BR.md)** — como reportar um bug, pedir uma feature e enviar um pull request.

package/dist/VSRepoAdapter.d.ts

@@ -108,4 +108,16 @@ export declare abstract class VSRepoAdapter<T> {
     abstract max(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
     /** Optional method for the adapter itself to return the "pkName", instead of the user having to configure it manually in the VSRepository constructor. */
     getPkName?(): string;
+    /**
+     * Optional method for the adapter to declare the placeholder syntax its
+     * database/driver expects in a raw `query()` string, given the 0-based
+     * position of the parameter in the `args` array (e.g. Postgres would
+     * return `` `$${index + 1}` ``, SQLite/MySQL would ignore `index` and
+     * always return `"?"`).
+     *
+     * Implementing this is what lets `VSRepository.query()` accept a `VSSql`
+     * fragment (built with `VSSql.sql`/`raw`/`join`/`empty`) in addition to a
+     * plain string: without it, passing a `VSSql` fragment throws.
+     */
+    getPlaceholder?(index: number): string;
 }

package/dist/VSRepoAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"VSRepoAdapter.js","sourceRoot":"","sources":["../src/VSRepoAdapter.ts"],"names":[],"mappings":";;;AAQA;;;;;;;;;;;GAWG;AACH,MAAsB,aAAa;CAgLlC;AAhLD,sCAgLC"}
+{"version":3,"file":"VSRepoAdapter.js","sourceRoot":"","sources":["../src/VSRepoAdapter.ts"],"names":[],"mappings":";;;AAQA;;;;;;;;;;;GAWG;AACH,MAAsB,aAAa;CA6LlC;AA7LD,sCA6LC"}