vsrepo 2.1.0 → 2.2.0

package/README.md

@@ -51,6 +51,7 @@ VSRepository lets you create strongly-typed repositories with:
     - [Ordering, pagination and distinct](#ordering-pagination-and-distinct)
     - [Decorator options](#decorator-options)
 - [Query methods (raw SQL)](#query-methods-raw-sql)
+    - [Spread arguments with `spreadArgs`](#spread-arguments-with-spreadargs)
     - [Ad-hoc raw queries with `query()`](#ad-hoc-raw-queries-with-query)
 - [Transactions](#transactions)
 - [Utility types](#utility-types)
@@ -598,21 +599,54 @@ class UserRepository extends VSRepository<User, string> {
 
     @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
     declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+
+    // Only one row is ever expected here, so `singleResult` collapses the
+    // array into a single object (or `null` when no row matches).
+    @QueryMethod('SELECT * FROM "user" WHERE id = $1 LIMIT 1', { singleResult: true })
+    declare findByIdRaw: (arg: QueryMethodArg<[id: string]>) => Promise<User | null>;
 }
 ```
 
-| Option      | Type      | Default | Description                                                                                                                                                                          |
-| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `modifying` | `boolean` | `false` | When `true`, runs as `INSERT`/`UPDATE`/`DELETE` and the method resolves to the number of affected rows. When `false`, runs as a read query and resolves to the declared return type. |
+| Option         | Type      | Default | Description                                                                                                                                                                          |
+| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `modifying`    | `boolean` | `false` | When `true`, runs as `INSERT`/`UPDATE`/`DELETE` and the method resolves to the number of affected rows. When `false`, runs as a read query and resolves to the declared return type. |
+| `singleResult` | `boolean` | `false` | When `true`, collapses an array result into its first element (`null` if empty), so you can declare the return type as a single object instead of an array. Has no effect on non-array results (e.g. a `modifying` query's affected-row count). |
 
 Query methods accept `{ args, db? }` at the call site — `db` lets them participate in a `transaction()` block just like base and dynamic methods.
 
+### Spread arguments with `spreadArgs`
+
+By default, a `@QueryMethod` receives its placeholder values through a single `QueryMethodArg` object (`method({ args: [...] })`). Set `spreadArgs: true` to receive them as separate positional arguments instead, JpaRepository style:
+
+```typescript
+class UserRepository extends VSRepository<User, string> {
+    @QueryMethod('SELECT * FROM "user" WHERE email = $1 AND "userType" = $2', {
+        spreadArgs: true,
+    })
+    declare findByEmailAndType: (
+        ...args: QueryArgs<[email: string, userType: string]>
+    ) => Promise<User[]>;
+}
+
+const admins = await userRepository.findByEmailAndType("joao@email.com", "admin");
+```
+
+To run the query against a specific client or transaction instead of the repository's default one, pass `withDb(tx)` as the trailing argument — it wraps `tx` in a `DbArg`, which the resolver recognizes with `instanceof`, so it's never confused with a regular positional argument even if that argument happens to be an object:
+
+```typescript
+await userRepository.transaction(async (tx) => {
+    await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
+});
+```
+
+`spreadArgs` only affects `@QueryMethod`-declared fields — it's `false` by default, and calling a method declared without it using more than one argument throws, since the single-`QueryMethodArg` call style is expected instead. It has no effect on `query()`, which always accepts `{ args, db? }`.
+
 ### Ad-hoc raw queries with `query()`
 
 For one-off raw SQL that doesn't warrant declaring a `@QueryMethod` on the repository class, call `query()` directly — it's available on every `VSRepository` instance and goes through the same adapter's `query()` implementation under the hood:
 
 ```typescript
-query<T = any>(query: string, options?: { args?: any[]; db?: any; modifying?: boolean }): Promise<T>;
+query<T = any>(query: string, options?: { args?: any[]; db?: any; modifying?: boolean; singleResult?: boolean }): Promise<T>;
 ```
 
 ```typescript
@@ -624,13 +658,21 @@ const affectedRows = await userRepository.query<number>(
     'UPDATE "user" SET active = true WHERE id = $1',
     { args: ["123"], modifying: true },
 );
+
+// Only one row is ever expected here, so `singleResult` collapses the
+// array into a single object (or `null` when no row matches).
+const user = await userRepository.query<User | null>(
+    'SELECT * FROM "user" WHERE id = $1 LIMIT 1',
+    { args: ["123"], singleResult: true },
+);
 ```
 
-| Option      | Type      | Default                     | Description                                                                                                              |
-| ----------- | --------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `args`      | `any[]`   | `undefined`                 | Positional parameters injected into `$1`, `$2`, ... placeholders. Never interpolate values directly into the SQL string. |
-| `db`        | `any`     | Repository's default client | Database client or transaction to run this query in.                                                                     |
-| `modifying` | `boolean` | `false`                     | When `true`, treats the statement as `INSERT`/`UPDATE`/`DELETE`.                                                         |
+| Option         | Type      | Default                     | Description                                                                                                                                                        |
+| -------------- | --------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `args`         | `any[]`   | `undefined`                  | Positional parameters injected into `$1`, `$2`, ... placeholders. Never interpolate values directly into the SQL string.                                          |
+| `db`           | `any`     | Repository's default client  | Database client or transaction to run this query in.                                                                                                              |
+| `modifying`    | `boolean` | `false`                      | When `true`, treats the statement as `INSERT`/`UPDATE`/`DELETE`.                                                                                                   |
+| `singleResult` | `boolean` | `false`                      | When `true`, collapses an array result into its first element (`null` if empty). Has no effect on non-array results (e.g. a `modifying` query's affected-row count). |
 
 Just like base, dynamic and query methods, `query()` accepts `db` in `options` to participate in a `transaction()` block.
 
@@ -691,6 +733,7 @@ import type {
     DeepPartial,
     CountResult,
     QueryMethodArg,
+    QueryArgs,
     KeysOfType,
     NumericKeys,
     NumericLike,
@@ -713,6 +756,7 @@ import type {
 | `DeepPartial<T>`                                    | Recursively makes every property of `T` optional, including nested objects and array elements.                                                                                                       | `save`, `saveList`, `patch`, `merge`, and every write method on `VSRepoAdapter`.                                                                              |
 | `CountResult`                                       | `{ count: number }` — the shape returned by batch operations.                                                                                                                                        | `removeList`, `softRemoveList`, `restoreList`, `createManyIgnoreConflicts`.                                                                                   |
 | `QueryMethodArg<T>`                                 | `{ args?: T, db? }` — positional SQL parameters (`$1`, `$2`, ...) and transaction client for `@QueryMethod`.                                                                                         | [Query methods (raw SQL)](#query-methods-raw-sql).                                                                                                            |
+| `QueryArgs<T, O>`                                   | Types the spread parameter list of a `@QueryMethod` declared with `{ spreadArgs: true }`: `T`'s values in order, followed by an optional trailing `DbArg<O>` built via `withDb()`.                  | [Spread arguments with `spreadArgs`](#spread-arguments-with-spreadargs).                                                                                      |
 | `KeysOfType<T, K>`                                  | Extracts the keys of `T` whose value type is assignable to `K`.                                                                                                                                      | Constrains `pkName` in [Constructor options](#constructor-options) to fields of the entity matching the configured primary-key type.                          |
 | `NumericKeys<T>`                                    | Extracts the keys of `T` whose (non-nullable) value type is assignable to `NumericLike`. Nullable numeric fields (`number \| null`) are included.                                                   | Constrains `field` in [Atomic and aggregate methods](#atomic-and-aggregate-methods) (`increment`, `sum`, etc).                                                |
 | `NumericLike`                                       | `number \| bigint \| DecimalLike`.                                                                                                                                                                    | [Atomic and aggregate methods](#atomic-and-aggregate-methods).                                                                                                 |
@@ -932,7 +976,7 @@ try {
 | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | `DECORATOR`       | Invalid arguments were passed to `@DynamicMethod` or `@QueryMethod`.                                                       |
 | `RESOLVER`        | The library failed to resolve a dynamic/query method's configuration into a callable method (e.g. an unknown method name). |
-| `DYNAMIC`         | A resolved dynamic method failed at runtime (e.g. missing arguments).                                                      |
+| `DYNAMIC`         | A resolved dynamic/query method failed at runtime (e.g. missing arguments).                                                      |
 | `VALIDATOR`       | Invalid method options or arguments were detected during validation.                                                       |
 | `BASE`            | Invalid usage of a base method (`get`, `save`, `remove`, etc).                                                             |
 | `ADAPTER`         | A `VSRepoAdapter` failed while talking to the underlying ORM/database — always thrown as `VSRepoAdapterError`.             |

package/README.pt-BR.md

@@ -51,6 +51,7 @@ O VSRepository permite criar repositories fortemente tipados com:
     - [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct)
     - [Options do decorador](#options-do-decorador)
 - [Query methods (SQL raw)](#query-methods-sql-raw)
+    - [Argumentos via spread com `spreadArgs`](#argumentos-via-spread-com-spreadargs)
     - [Queries raw pontuais com `query()`](#queries-raw-pontuais-com-query)
 - [Transações](#transações)
 - [Tipos utilitários](#tipos-utilitários)
@@ -598,21 +599,54 @@ class UserRepository extends VSRepository<User, string> {
 
     @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
     declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+
+    // Aqui só se espera uma linha, então `singleResult` transforma o array
+    // em um único objeto (ou `null` quando nenhuma linha corresponde).
+    @QueryMethod('SELECT * FROM "user" WHERE id = $1 LIMIT 1', { singleResult: true })
+    declare findByIdRaw: (arg: QueryMethodArg<[id: string]>) => Promise<User | null>;
 }
 ```
 
-| Option      | Tipo      | Padrão  | Descrição                                                                                                                                                                                             |
-| ----------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `modifying` | `boolean` | `false` | Quando `true`, executa como `INSERT`/`UPDATE`/`DELETE` e o método resolve para o número de linhas afetadas. Quando `false`, executa como query de leitura e resolve para o tipo de retorno declarado. |
+| Option         | Tipo      | Padrão  | Descrição                                                                                                                                                                                             |
+| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modifying`    | `boolean` | `false` | Quando `true`, executa como `INSERT`/`UPDATE`/`DELETE` e o método resolve para o número de linhas afetadas. Quando `false`, executa como query de leitura e resolve para o tipo de retorno declarado. |
+| `singleResult` | `boolean` | `false` | Quando `true`, transforma um resultado em array no seu primeiro elemento (`null` se vazio), permitindo declarar o tipo de retorno como um objeto único em vez de array. Não tem efeito em resultados que não são array (ex.: o número de linhas afetadas de uma query `modifying`). |
 
 Query methods aceitam `{ args, db? }` na chamada — `db` permite que participem de um bloco `transaction()`, assim como os métodos base e dinâmicos.
 
+### Argumentos via spread com `spreadArgs`
+
+Por padrão, um `@QueryMethod` recebe seus valores de placeholder através de um único objeto `QueryMethodArg` (`method({ args: [...] })`). Defina `spreadArgs: true` para recebê-los como argumentos posicionais separados, no estilo do JpaRepository:
+
+```typescript
+class UserRepository extends VSRepository<User, string> {
+    @QueryMethod('SELECT * FROM "user" WHERE email = $1 AND "userType" = $2', {
+        spreadArgs: true,
+    })
+    declare findByEmailAndType: (
+        ...args: QueryArgs<[email: string, userType: string]>
+    ) => Promise<User[]>;
+}
+
+const admins = await userRepository.findByEmailAndType("joao@email.com", "admin");
+```
+
+Para rodar a query com um client ou transação específico em vez do client padrão do repository, passe `withDb(tx)` como argumento final — ele embrulha `tx` em um `DbArg`, que o resolver reconhece via `instanceof`, então nunca é confundido com um argumento posicional comum, mesmo que esse argumento seja um objeto:
+
+```typescript
+await userRepository.transaction(async (tx) => {
+    await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
+});
+```
+
+`spreadArgs` afeta apenas campos declarados com `@QueryMethod` — o padrão é `false`, e chamar um método declarado sem essa opção usando mais de um argumento lança erro, já que se espera o estilo de chamada com um único `QueryMethodArg`. Não tem efeito sobre `query()`, que sempre aceita `{ args, db? }`.
+
 ### Queries raw pontuais com `query()`
 
 Para SQL raw pontual que não justifica declarar um `@QueryMethod` na classe do repository, chame `query()` diretamente — ele está disponível em toda instância de `VSRepository` e passa pela mesma implementação de `query()` do adapter por baixo dos panos:
 
 ```typescript
-query<T = any>(query: string, options?: { args?: any[]; db?: any; modifying?: boolean }): Promise<T>;
+query<T = any>(query: string, options?: { args?: any[]; db?: any; modifying?: boolean; singleResult?: boolean }): Promise<T>;
 ```
 
 ```typescript
@@ -624,13 +658,21 @@ const linhasAfetadas = await userRepository.query<number>(
     'UPDATE "user" SET active = true WHERE id = $1',
     { args: ["123"], modifying: true },
 );
+
+// Aqui só se espera uma linha, então `singleResult` transforma o array
+// em um único objeto (ou `null` quando nenhuma linha corresponde).
+const user = await userRepository.query<User | null>(
+    'SELECT * FROM "user" WHERE id = $1 LIMIT 1',
+    { args: ["123"], singleResult: true },
+);
 ```
 
-| Option      | Tipo      | Padrão                      | Descrição                                                                                                            |
-| ----------- | --------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `args`      | `any[]`   | `undefined`                 | Parâmetros posicionais injetados nos placeholders `$1`, `$2`, ... Nunca interpole valores diretamente na string SQL. |
-| `db`        | `any`     | Client padrão do repository | Client ou transação do banco em que essa query deve rodar.                                                           |
-| `modifying` | `boolean` | `false`                     | Quando `true`, trata a instrução como `INSERT`/`UPDATE`/`DELETE`.                                                    |
+| Option         | Tipo      | Padrão                      | Descrição                                                                                                                                             |
+| -------------- | --------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `args`         | `any[]`   | `undefined`                  | Parâmetros posicionais injetados nos placeholders `$1`, `$2`, ... Nunca interpole valores diretamente na string SQL.                                  |
+| `db`           | `any`     | Client padrão do repository  | Client ou transação do banco em que essa query deve rodar.                                                                                             |
+| `modifying`    | `boolean` | `false`                      | Quando `true`, trata a instrução como `INSERT`/`UPDATE`/`DELETE`.                                                                                      |
+| `singleResult` | `boolean` | `false`                      | Quando `true`, transforma um resultado em array no seu primeiro elemento (`null` se vazio). Não tem efeito em resultados que não são array (ex.: o número de linhas afetadas de uma query `modifying`). |
 
 Assim como os métodos base, dinâmicos e query, `query()` aceita `db` em `options` para participar de um bloco `transaction()`.
 
@@ -694,6 +736,7 @@ import type {
     DeepPartial,
     CountResult,
     QueryMethodArg,
+    QueryArgs,
     KeysOfType,
     NumericKeys,
     NumericLike,
@@ -716,6 +759,7 @@ import type {
 | `DeepPartial<T>`                                    | Torna todas as propriedades de `T` opcionais recursivamente, incluindo objetos aninhados e elementos de array.                                                                                                      | `save`, `saveList`, `patch`, `merge`, e todo método de escrita do `VSRepoAdapter`.                                                                                  |
 | `CountResult`                                       | `{ count: number }` — o formato retornado por operações em lote.                                                                                                                                                    | `removeList`, `softRemoveList`, `restoreList`, `createManyIgnoreConflicts`.                                                                                         |
 | `QueryMethodArg<T>`                                 | `{ args?: T, db? }` — parâmetros posicionais do SQL (`$1`, `$2`, ...) e cliente de transação para o `@QueryMethod`.                                                                                                 | [Query methods (SQL raw)](#query-methods-sql-raw).                                                                                                                  |
+| `QueryArgs<T, O>`                                   | Tipa a lista de parâmetros via spread de um `@QueryMethod` declarado com `{ spreadArgs: true }`: os valores de `T`, em ordem, seguidos de um `DbArg<O>` opcional construído via `withDb()`.                       | [Argumentos via spread com `spreadArgs`](#argumentos-via-spread-com-spreadargs).                                                                                    |
 | `KeysOfType<T, K>`                                  | Extrai as chaves de `T` cujo tipo de valor é atribuível a `K`.                                                                                                                                                      | Restringe `pkName`, em [Options do construtor](#options-do-construtor), aos campos da entidade compatíveis com o tipo de chave primária configurado.                |
 | `NumericKeys<T>`                                    | Extrai as chaves de `T` cujo tipo de valor (ignorando `null`/`undefined`) é atribuível a `NumericLike`. Campos numéricos nullable (`number \| null`) são incluídos.                                                | Restringe `field` em [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação) (`increment`, `sum`, etc).                                                 |
 | `NumericLike`                                       | `number \| bigint \| DecimalLike`.                                                                                                                                                                                   | [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação).                                                                                                 |
@@ -935,7 +979,7 @@ try {
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | `DECORATOR`       | Argumentos inválidos foram passados para `@DynamicMethod` ou `@QueryMethod`.                                                               |
 | `RESOLVER`        | A biblioteca falhou ao resolver a configuração de um método dinâmico/de query em um método chamável (ex.: um nome de método desconhecido). |
-| `DYNAMIC`         | Um método dinâmico já resolvido falhou em tempo de execução (ex.: argumentos faltando).                                                    |
+| `DYNAMIC`         | Um dynamic/query method já resolvido falhou em tempo de execução (ex.: argumentos faltando).                                                    |
 | `VALIDATOR`       | Options ou argumentos de método inválidos foram detectados durante a validação.                                                            |
 | `BASE`            | Uso inválido de um método base (`get`, `save`, `remove`, etc).                                                                             |
 | `ADAPTER`         | Um `VSRepoAdapter` falhou ao falar com o ORM/banco subjacente — sempre é lançado como `VSRepoAdapterError`.                                |

package/dist/VSRepository.d.ts

@@ -79,6 +79,8 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
      * Use `$1`, `$2`, ... placeholders for values passed via `options.args` —
      * never interpolate values directly into `query`, to avoid SQL injection.
      * Set `options.modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements.
+     * Set `options.singleResult: true` to collapse an array result into its
+     * first element (`null` if empty) — see {@link VSRepoQueryOptions.singleResult}.
      *
      * @example
      * ```typescript
@@ -91,6 +93,13 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
      *     'UPDATE "user" SET active = true WHERE id = $1',
      *     { args: ["123"], modifying: true },
      * );
+     *
+     * // Only one row is ever expected here, so `singleResult` collapses the
+     * // array into a single object (or `null` when no row matches).
+     * const user = await userRepository.query<User | null>(
+     *     'SELECT * FROM "user" WHERE id = $1 LIMIT 1',
+     *     { args: ["123"], singleResult: true },
+     * );
      * ```
      */
     query<T = any>(query: string, options?: VSRepoQueryOptions<OrmTypes>): Promise<T>;

package/dist/VSRepository.js

@@ -141,6 +141,8 @@ class VSRepository {
      * Use `$1`, `$2`, ... placeholders for values passed via `options.args` —
      * never interpolate values directly into `query`, to avoid SQL injection.
      * Set `options.modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements.
+     * Set `options.singleResult: true` to collapse an array result into its
+     * first element (`null` if empty) — see {@link VSRepoQueryOptions.singleResult}.
      *
      * @example
      * ```typescript
@@ -153,6 +155,13 @@ class VSRepository {
      *     'UPDATE "user" SET active = true WHERE id = $1',
      *     { args: ["123"], modifying: true },
      * );
+     *
+     * // Only one row is ever expected here, so `singleResult` collapses the
+     * // array into a single object (or `null` when no row matches).
+     * const user = await userRepository.query<User | null>(
+     *     'SELECT * FROM "user" WHERE id = $1 LIMIT 1',
+     *     { args: ["123"], singleResult: true },
+     * );
      * ```
      */
     async query(query, options) {
@@ -168,8 +177,11 @@ class VSRepository {
                 db: optionsValidated.db,
                 modifying: optionsValidated.modifying ?? false,
             });
+            const resolved = optionsValidated.singleResult && Array.isArray(result)
+                ? (result[0] ?? null)
+                : result;
             this.logger.endPerformLog(start);
-            return result;
+            return resolved;
         }
         catch (err) {
             this.logger.endPerformLog(start);

package/dist/decorators/query-method.decorator.d.ts

@@ -1,15 +1,20 @@
-import { QueryMethodOptions } from "../types/decorators/query-method-options.type";
+import type { QueryMethodOptions } from "../types/decorators/query-method-options.type";
 /**
  * Property decorator used to declare a raw SQL query method on a `VSRepository`
  * subclass, bypassing name-based method parsing entirely.
  *
  * Applied to a `declare` class field, it executes `value` directly through the
  * adapter's `query()` method, with parameters injected positionally via the
- * `args` array passed at the call site (`$1`, `$2`, ... placeholders).
+ * `args` array passed at the call site (`$1`, `$2`, ... placeholders) — or,
+ * with `spreadArgs: true`, via separate positional arguments instead.
  *
  * @param value Raw SQL statement to execute. Use `$1`, `$2`, ... placeholders for
  * the values that will be passed via `args` — never interpolate values directly into `value`.
- * @param options Optional configuration; set `modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements.
+ * @param options Optional configuration; set `modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements,
+ * `singleResult: true` to collapse an array result into its first element, and
+ * `spreadArgs: true` to receive placeholder values as separate arguments instead of a
+ * single `QueryMethodArg` object — see {@link QueryMethodOptions.singleResult} and
+ * {@link QueryMethodOptions.spreadArgs}.
  *
  * @example
  * ```typescript
@@ -19,7 +24,25 @@ import { QueryMethodOptions } from "../types/decorators/query-method-options.typ
  *
  *     @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
  *     declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+ *
+ *     // Only one row is ever expected here, so `singleResult` collapses the
+ *     // array into a single object (or `null` when no row matches).
+ *     @QueryMethod('SELECT * FROM "user" WHERE id = $1 LIMIT 1', { singleResult: true })
+ *     declare findByIdRaw: (arg: QueryMethodArg<[id: string]>) => Promise<User | null>;
+ *
+ *     // `spreadArgs: true` takes placeholder values as separate arguments,
+ *     // JpaRepository style, instead of a single `{ args: [...] }` object.
+ *     // An optional trailing `withDb(tx)` runs the query in a transaction.
+ *     @QueryMethod('SELECT * FROM "user" WHERE email = $1 AND "userType" = $2', {
+ *         spreadArgs: true,
+ *     })
+ *     declare findByEmailAndType: (
+ *         ...args: QueryArgs<[email: string, userType: string]>
+ *     ) => Promise<User[]>;
  * }
+ *
+ * await userRepository.findByEmailAndType("joao@email.com", "admin");
+ * await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
  * ```
  *
  * @publicApi

package/dist/decorators/query-method.decorator.js

@@ -11,11 +11,16 @@ const decorators_validator_1 = require("../internal/validators/decorators.valida
  *
  * Applied to a `declare` class field, it executes `value` directly through the
  * adapter's `query()` method, with parameters injected positionally via the
- * `args` array passed at the call site (`$1`, `$2`, ... placeholders).
+ * `args` array passed at the call site (`$1`, `$2`, ... placeholders) — or,
+ * with `spreadArgs: true`, via separate positional arguments instead.
  *
  * @param value Raw SQL statement to execute. Use `$1`, `$2`, ... placeholders for
  * the values that will be passed via `args` — never interpolate values directly into `value`.
- * @param options Optional configuration; set `modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements.
+ * @param options Optional configuration; set `modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements,
+ * `singleResult: true` to collapse an array result into its first element, and
+ * `spreadArgs: true` to receive placeholder values as separate arguments instead of a
+ * single `QueryMethodArg` object — see {@link QueryMethodOptions.singleResult} and
+ * {@link QueryMethodOptions.spreadArgs}.
  *
  * @example
  * ```typescript
@@ -25,7 +30,25 @@ const decorators_validator_1 = require("../internal/validators/decorators.valida
  *
  *     @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
  *     declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+ *
+ *     // Only one row is ever expected here, so `singleResult` collapses the
+ *     // array into a single object (or `null` when no row matches).
+ *     @QueryMethod('SELECT * FROM "user" WHERE id = $1 LIMIT 1', { singleResult: true })
+ *     declare findByIdRaw: (arg: QueryMethodArg<[id: string]>) => Promise<User | null>;
+ *
+ *     // `spreadArgs: true` takes placeholder values as separate arguments,
+ *     // JpaRepository style, instead of a single `{ args: [...] }` object.
+ *     // An optional trailing `withDb(tx)` runs the query in a transaction.
+ *     @QueryMethod('SELECT * FROM "user" WHERE email = $1 AND "userType" = $2', {
+ *         spreadArgs: true,
+ *     })
+ *     declare findByEmailAndType: (
+ *         ...args: QueryArgs<[email: string, userType: string]>
+ *     ) => Promise<User[]>;
  * }
+ *
+ * await userRepository.findByEmailAndType("joao@email.com", "admin");
+ * await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
  * ```
  *
  * @publicApi

package/dist/index.d.ts

@@ -3,12 +3,14 @@ export { VSRepository } from "./VSRepository.js";
 export { VSRepoAdapter } from "./VSRepoAdapter.js";
 export { VSRepoError } from "./errors/VSRepoError.js";
 export { VSRepoAdapterError } from "./errors/VSRepoAdapterError.js";
+export { DbArg } from "./internal/utils/db-arg.util.js";
 export { DynamicMethod } from "./decorators/dynamic-method.decorator.js";
 export { QueryMethod } from "./decorators/query-method.decorator.js";
 export { VSRepoErrorType } from "./internal/enums/vsrepo-error-type.enum.js";
 export { VSLogLevel } from "./internal/enums/vs-log-level.enum.js";
 export { TransactionIsolationLevel } from "./internal/enums/transaction-isolation-level.enum.js";
 export { AdapterErrorCode } from "./internal/enums/adapter-error-code.enum.js";
+export { withDb } from "./internal/utils/with-db.util.js";
 export type { VSRepoOptions } from "./types/vsrepo/vsrepo-options.type.js";
 export type { VSRepoOrmTypes } from "./types/vsrepo/vsrepo-orm-types.type.js";
 export type { VSRepoArgs } from "./types/vsrepo/vsrepo-args.type.js";
@@ -35,4 +37,5 @@ export type { DecimalLike } from "./types/utils/decimal-like.type.js";
 export type { NumericKeys } from "./types/utils/numeric-keys.type.js";
 export type { NumericLike } from "./types/utils/numeric-like.type.js";
 export type { RestrictMethodOptions } from "./types/utils/restrict-method-options.type.js";
+export type { QueryArgs } from "./types/utils/query-args.type.js";
 export { VSLogger } from "./internal/utils/vs-logger.util.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VSLogger = exports.AdapterErrorCode = exports.TransactionIsolationLevel = exports.VSLogLevel = exports.VSRepoErrorType = exports.QueryMethod = exports.DynamicMethod = exports.VSRepoAdapterError = exports.VSRepoError = exports.VSRepoAdapter = exports.VSRepository = void 0;
+exports.VSLogger = exports.withDb = exports.AdapterErrorCode = exports.TransactionIsolationLevel = exports.VSLogLevel = exports.VSRepoErrorType = exports.QueryMethod = exports.DynamicMethod = exports.DbArg = exports.VSRepoAdapterError = exports.VSRepoError = exports.VSRepoAdapter = exports.VSRepository = void 0;
 require("reflect-metadata");
 // Public classes / constructors
 var VSRepository_js_1 = require("./VSRepository.js");
@@ -11,6 +11,8 @@ var VSRepoError_js_1 = require("./errors/VSRepoError.js");
 Object.defineProperty(exports, "VSRepoError", { enumerable: true, get: function () { return VSRepoError_js_1.VSRepoError; } });
 var VSRepoAdapterError_js_1 = require("./errors/VSRepoAdapterError.js");
 Object.defineProperty(exports, "VSRepoAdapterError", { enumerable: true, get: function () { return VSRepoAdapterError_js_1.VSRepoAdapterError; } });
+var db_arg_util_js_1 = require("./internal/utils/db-arg.util.js");
+Object.defineProperty(exports, "DbArg", { enumerable: true, get: function () { return db_arg_util_js_1.DbArg; } });
 // Decorators
 var dynamic_method_decorator_js_1 = require("./decorators/dynamic-method.decorator.js");
 Object.defineProperty(exports, "DynamicMethod", { enumerable: true, get: function () { return dynamic_method_decorator_js_1.DynamicMethod; } });
@@ -25,6 +27,9 @@ var transaction_isolation_level_enum_js_1 = require("./internal/enums/transactio
 Object.defineProperty(exports, "TransactionIsolationLevel", { enumerable: true, get: function () { return transaction_isolation_level_enum_js_1.TransactionIsolationLevel; } });
 var adapter_error_code_enum_js_1 = require("./internal/enums/adapter-error-code.enum.js");
 Object.defineProperty(exports, "AdapterErrorCode", { enumerable: true, get: function () { return adapter_error_code_enum_js_1.AdapterErrorCode; } });
+// Public functions
+var with_db_util_js_1 = require("./internal/utils/with-db.util.js");
+Object.defineProperty(exports, "withDb", { enumerable: true, get: function () { return with_db_util_js_1.withDb; } });
 // Internal features
 var vs_logger_util_js_1 = require("./internal/utils/vs-logger.util.js");
 Object.defineProperty(exports, "VSLogger", { enumerable: true, get: function () { return vs_logger_util_js_1.VSLogger; } });

package/dist/internal/enums/vsrepo-error-type.enum.d.ts

@@ -8,7 +8,7 @@ export declare enum VSRepoErrorType {
     DECORATOR = "DECORATOR",
     /** Failure while resolving a dynamic or query method's configuration into a callable method. */
     RESOLVER = "RESOLVER",
-    /** Failure while executing a resolved dynamic method at runtime. */
+    /** Failure while executing a resolved dynamic/query method at runtime. */
     DYNAMIC = "DYNAMIC",
     /** Invalid method options or arguments detected during validation. */
     VALIDATOR = "VALIDATOR",

package/dist/internal/enums/vsrepo-error-type.enum.js

@@ -12,7 +12,7 @@ var VSRepoErrorType;
     VSRepoErrorType["DECORATOR"] = "DECORATOR";
     /** Failure while resolving a dynamic or query method's configuration into a callable method. */
     VSRepoErrorType["RESOLVER"] = "RESOLVER";
-    /** Failure while executing a resolved dynamic method at runtime. */
+    /** Failure while executing a resolved dynamic/query method at runtime. */
     VSRepoErrorType["DYNAMIC"] = "DYNAMIC";
     /** Invalid method options or arguments detected during validation. */
     VSRepoErrorType["VALIDATOR"] = "VALIDATOR";

package/dist/internal/resolvers/dynamic-methods.resolver.js

@@ -12,6 +12,7 @@ const uncapitalize_util_1 = require("../utils/uncapitalize.util");
 const deepmerge_1 = __importDefault(require("deepmerge"));
 const vsrepo_error_type_enum_1 = require("../enums/vsrepo-error-type.enum");
 const debug_arg_symbol_constant_1 = require("../constants/debug-arg-symbol.constant");
+const db_arg_util_1 = require("../utils/db-arg.util");
 class DynamicMethodsResolver {
     logger;
     adapter;
@@ -880,19 +881,44 @@ class DynamicMethodsResolver {
         this.logger.logDebug(`Resolving ${queryMethods.length} query method(s):`, queryMethods);
         for (const method of queryMethods) {
             const originalKey = method.propertyKey;
-            const modifyingQueryMethod = method.modifying;
+            const modifyingQueryMethod = method.modifying ?? false;
             const valueQueryMethod = method.value;
-            instance[originalKey] = async (arg) => {
-                const queryArgValidated = this.validator.validateQueryMethodArg(arg);
-                queryArgValidated.db ??= this.adapter.getDbClient();
+            const singleResult = method.singleResult;
+            const spreadArgsMode = method.spreadArgs;
+            instance[originalKey] = async (...args) => {
+                let db;
+                let queryArgs;
+                if (spreadArgsMode) {
+                    const dbPos = args.at(-1);
+                    if (dbPos instanceof db_arg_util_1.DbArg) {
+                        db = dbPos.getDb();
+                        queryArgs = args.slice(0, -1);
+                    }
+                    else {
+                        queryArgs = args;
+                    }
+                }
+                else {
+                    if (args.length > 1) {
+                        const errorMessage = `This query method was declared without spreadArgs = true, use a single QueryMethodArg instead`;
+                        this.logger.logError(`Cannot run '${String(originalKey)}': ${errorMessage}`);
+                        throw new VSRepoError_1.VSRepoError(errorMessage, vsrepo_error_type_enum_1.VSRepoErrorType.DYNAMIC);
+                    }
+                    const queryArgValidated = this.validator.validateQueryMethodArg(args[0]);
+                    db = queryArgValidated.db;
+                    queryArgs = queryArgValidated.args;
+                }
+                db ??= this.adapter.getDbClient();
                 const start = this.logger.startPerformLog(`run ${String(originalKey)} (Modifying: ${modifyingQueryMethod})`);
                 try {
                     const result = await this.adapter.query(valueQueryMethod, {
-                        ...queryArgValidated,
+                        db,
+                        args: queryArgs,
                         modifying: modifyingQueryMethod,
                     });
+                    const resolved = singleResult && Array.isArray(result) ? (result[0] ?? null) : result;
                     this.logger.endPerformLog(start);
-                    return result;
+                    return resolved;
                 }
                 catch (err) {
                     this.logger.endPerformLog(start);

package/dist/internal/utils/db-arg.util.d.ts

@@ -0,0 +1,15 @@
+import { VSRepoOrmTypes } from "../../types/vsrepo/vsrepo-orm-types.type";
+/**
+ * Wraps a database client or transaction so it can be recognized, at
+ * runtime, as the trailing `db` override in a {@link QueryArgs} spread call —
+ * as opposed to a regular positional query argument. Build one with
+ * {@link withDb} rather than constructing it directly.
+ *
+ * @publicApi
+ */
+export declare class DbArg<T extends VSRepoOrmTypes = VSRepoOrmTypes> {
+    private readonly db;
+    constructor(db: T["dbClient"] | T["dbTransaction"]);
+    /** Returns the wrapped database client or transaction. */
+    getDb(): T["dbClient"] | T["dbTransaction"];
+}

package/dist/internal/utils/db-arg.util.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbArg = void 0;
+/**
+ * Wraps a database client or transaction so it can be recognized, at
+ * runtime, as the trailing `db` override in a {@link QueryArgs} spread call —
+ * as opposed to a regular positional query argument. Build one with
+ * {@link withDb} rather than constructing it directly.
+ *
+ * @publicApi
+ */
+class DbArg {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Returns the wrapped database client or transaction. */
+    getDb() {
+        return this.db;
+    }
+}
+exports.DbArg = DbArg;

package/dist/internal/utils/with-db.util.d.ts

@@ -0,0 +1,19 @@
+import { VSRepoOrmTypes } from "../../types/vsrepo/vsrepo-orm-types.type";
+import { DbArg } from "./db-arg.util";
+/**
+ * Wraps a database client or transaction so it can be passed as the
+ * trailing argument of a `@QueryMethod` declared with `{ spreadArgs: true }`,
+ * running that call against `db` instead of the repository's default
+ * client — the same role `{ db }` plays in the single-object
+ * `QueryMethodArg` call style.
+ *
+ * @example
+ * ```typescript
+ * await userRepository.transaction(async (tx) => {
+ *     await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
+ * });
+ * ```
+ *
+ * @publicApi
+ */
+export declare function withDb<T extends VSRepoOrmTypes = VSRepoOrmTypes>(db: T["dbClient"] | T["dbTransaction"]): DbArg<T>;

package/dist/internal/utils/with-db.util.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDb = withDb;
+const db_arg_util_1 = require("./db-arg.util");
+/**
+ * Wraps a database client or transaction so it can be passed as the
+ * trailing argument of a `@QueryMethod` declared with `{ spreadArgs: true }`,
+ * running that call against `db` instead of the repository's default
+ * client — the same role `{ db }` plays in the single-object
+ * `QueryMethodArg` call style.
+ *
+ * @example
+ * ```typescript
+ * await userRepository.transaction(async (tx) => {
+ *     await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
+ * });
+ * ```
+ *
+ * @publicApi
+ */
+function withDb(db) {
+    return new db_arg_util_1.DbArg(db);
+}

package/dist/internal/validators/decorators.validator.js

@@ -59,6 +59,8 @@ class DecoratorsValidator {
     }
     static queryMethodOptionsSchema = v.object({
         modifying: v.optional(v.boolean(), false),
+        singleResult: v.optional(v.boolean()),
+        spreadArgs: v.optional(v.boolean()),
     });
     static validateQueryMethodOptions(options) {
         const parsed = v.safeParse(this.queryMethodOptionsSchema, options);

package/dist/internal/validators/vsrepo.validator.d.ts

@@ -26,7 +26,7 @@ export declare class VSRepoValidator<T, K, O extends VSRepoOrmTypes = VSRepoOrmT
         order?: Ordering<T>;
     };
     private queryArgSchema;
-    validateQueryMethodArg(arg?: unknown): QueryMethodArg<any>;
+    validateQueryMethodArg(arg?: unknown): QueryMethodArg<any[]>;
     private queryOptionsSchema;
     validateQueryOptions(options?: unknown): VSRepoQueryOptions;
     private transactionOptionsSchema;

package/dist/internal/validators/vsrepo.validator.js

@@ -127,6 +127,7 @@ class VSRepoValidator {
         args: v.optional(v.array(v.any())),
         db: v.optional(v.any()),
         modifying: v.optional(v.boolean()),
+        singleResult: v.optional(v.boolean()),
     });
     validateQueryOptions(options) {
         const parsed = v.safeParse(this.queryOptionsSchema, options ?? {});

package/dist/types/decorators/query-method-options.type.d.ts

@@ -11,5 +11,39 @@ export type QueryMethodOptions = {
      * to whatever return type is declared on the field.
      * @default false
      */
-    modifying: boolean;
+    modifying?: boolean;
+    /**
+     * When `true`, the array returned by the underlying query is collapsed
+     * into its first element (`null` if the array is empty) before
+     * being resolved to the caller. Has no effect when the query resolves
+     * to something other than an array (e.g. a `modifying` query's
+     * affected-row count).
+     *
+     * Useful for queries you already know return at most one row (e.g. a
+     * `SELECT ... LIMIT 1` or a lookup by a unique column), where declaring
+     * the return type as an array would be misleading.
+     *
+     * @default false
+     */
+    singleResult?: boolean;
+    /**
+     * When `true`, the decorated method receives its SQL placeholder values
+     * as separate positional arguments (`method(a, b, c)`) instead of a
+     * single {@link QueryMethodArg} object (`method({ args: [a, b, c] })`).
+     * Type the declared field's parameters with {@link QueryArgs} to get
+     * autocompletion and arity checking for this call style.
+     *
+     * To run the query against a specific client or transaction — instead
+     * of the repository's default one — pass {@link DbArg} (built via
+     * {@link withDb}) as the trailing argument: `method(a, b, withDb(tx))`.
+     * It's recognized by `instanceof`, so it never collides with a regular
+     * positional argument, even one that happens to be an object.
+     *
+     * When `false` (the default), calling the method with more than one
+     * argument throws, since it expects the single-object `QueryMethodArg`
+     * call style instead.
+     *
+     * @default false
+     */
+    spreadArgs?: boolean;
 };

package/dist/types/utils/query-args.type.d.ts

@@ -0,0 +1,30 @@
+import { DbArg } from "../../internal/utils/db-arg.util";
+import { VSRepoOrmTypes } from "../vsrepo/vsrepo-orm-types.type";
+/**
+ * Types the parameter list of a `@QueryMethod` declared with
+ * `{ spreadArgs: true }`: the SQL placeholder values (`T`), in order,
+ * followed by an optional trailing {@link DbArg} — built via {@link withDb} —
+ * to run the query against a specific client or transaction instead of the
+ * repository's default one.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends VSRepository<User, string> {
+ *     @QueryMethod('SELECT * FROM "user" WHERE email = $1 AND "userType" = $2', {
+ *         spreadArgs: true,
+ *     })
+ *     declare findByEmailAndType: (
+ *         ...args: QueryArgs<[email: string, userType: string]>
+ *     ) => Promise<User[]>;
+ * }
+ *
+ * await userRepository.findByEmailAndType("joao@email.com", "admin");
+ * await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
+ * ```
+ *
+ * @publicApi
+ */
+export type QueryArgs<T extends Array<any> = [], O extends VSRepoOrmTypes = VSRepoOrmTypes> = [
+    ...T,
+    db?: DbArg<O>
+];

package/dist/types/utils/query-args.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/utils/query-method-arg.type.d.ts

@@ -1,3 +1,4 @@
+import { VSRepoOrmTypes } from "../vsrepo/vsrepo-orm-types.type";
 /**
  * Single argument accepted by a method declared with `@QueryMethod`.
  *
@@ -19,9 +20,9 @@
  *
  * @publicApi
  */
-export type QueryMethodArg<T extends Array<any>> = {
+export type QueryMethodArg<T extends Array<any> = [], O extends VSRepoOrmTypes = VSRepoOrmTypes> = {
     /** Positional parameters injected into the SQL placeholders (`$1`, `$2`, ...). */
     args?: T;
     /** Database client or transaction to run this query in, instead of the repository's default client. */
-    db?: any;
+    db?: O["dbClient"] | O["dbTransaction"];
 };

package/dist/types/vsrepo/vsrepo-query-options.type.d.ts

@@ -14,4 +14,18 @@ export type VSRepoQueryOptions<T extends VSRepoOrmTypes = VSRepoOrmTypes> = {
      * @default false
      */
     modifying?: boolean;
+    /**
+     * When `true`, the array returned by the underlying query is collapsed
+     * into its first element (`null` if the array is empty) before
+     * being resolved to the caller. Has no effect when the query resolves
+     * to something other than an array (e.g. a `modifying` query's
+     * affected-row count).
+     *
+     * Useful for queries you already know return at most one row (e.g. a
+     * `SELECT ... LIMIT 1` or a lookup by a unique column), where declaring
+     * the return type as an array would be misleading.
+     *
+     * @default false
+     */
+    singleResult?: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vsrepo",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "ORM-agnostic repository pattern library with full TypeScript support and automatic type inference.",
   "homepage": "https://github.com/jaobrabo123/VSRepository#readme",
   "repository": {