vsrepo 2.0.0 → 2.2.0

package/dist/VSRepository.js

@@ -102,10 +102,12 @@ class VSRepository {
     wherePkIn(pks) {
         return { [this.pkName]: { in: pks } };
     }
-    async execBaseMethod(fn, methodName, optionsUnchecked) {
-        const optionsChecked = methodName === "getAll"
-            ? this.validator.validateGetAllMethodOptions(optionsUnchecked)
-            : this.validator.validateMethodOptions(optionsUnchecked);
+    async execBaseMethod(fn, methodName, optionsUnchecked, opsType = "common") {
+        const optionsChecked = opsType === "common"
+            ? this.validator.validateMethodOptions(optionsUnchecked)
+            : opsType === "restrict"
+                ? this.validator.validateRestrictMethodOptions(optionsUnchecked)
+                : this.validator.validateGetAllMethodOptions(optionsUnchecked);
         optionsChecked.db ??= this.getDbClient();
         const start = this.logger.startPerformLog("run " + methodName);
         try {
@@ -139,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
@@ -151,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) {
@@ -166,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);
@@ -195,7 +209,7 @@ class VSRepository {
         return this.execBaseMethod((opt) => this.adapter.findMany(this.mergeWheresResolver.resolve(opt.see, {}), {
             ...opt,
             order: opt.order ?? this.defaultOrdering,
-        }), "getAll", options);
+        }), "getAll", options, "getAll");
     }
     /** Creates or updates (upsert) a record. */
     async save(obj, options) {
@@ -217,7 +231,7 @@ class VSRepository {
         if (!Array.isArray(pks)) {
             this.fail("'pks' must be a valid array", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
         }
-        return this.execBaseMethod(opt => this.adapter.deleteMany(this.mergeWheresResolver.resolve(opt.see, this.wherePkIn(pks)), opt), "removeList", options);
+        return this.execBaseMethod(opt => this.adapter.deleteMany(this.mergeWheresResolver.resolve(opt.see, this.wherePkIn(pks)), opt), "removeList", options, "restrict");
     }
     /** Partially updates an existing record by its primary key (PK). */
     async patch(pk, obj, options) {
@@ -233,11 +247,11 @@ class VSRepository {
     }
     /** Returns the total number of records. */
     async total(options) {
-        return this.execBaseMethod(opt => this.adapter.count(this.mergeWheresResolver.resolve(opt.see, {}), opt), "total", options);
+        return this.execBaseMethod(opt => this.adapter.count(this.mergeWheresResolver.resolve(opt.see, {}), opt), "total", options, "restrict");
     }
     /** Checks whether a record exists by its primary key (PK). */
     async has(pk, options) {
-        return this.execBaseMethod(opt => this.adapter.exists(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "has", options);
+        return this.execBaseMethod(opt => this.adapter.exists(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "has", options, "restrict");
     }
     /** Marks a record as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
     async softRemove(pk, options) {
@@ -256,7 +270,7 @@ class VSRepository {
             this.fail("'pks' must be a valid array", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
         }
         const key = this.softRemoveKey;
-        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: new Date() }, opt), "softRemoveList", options);
+        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: new Date() }, opt), "softRemoveList", options, "restrict");
     }
     /** Restores a record previously marked as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
     async restore(pk, options) {
@@ -275,7 +289,59 @@ class VSRepository {
             this.fail("'pks' must be a valid array", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
         }
         const key = this.softRemoveKey;
-        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: null }, opt), "restoreList", options);
+        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: null }, opt), "restoreList", options, "restrict");
+    }
+    /**
+     * Atomically adds `value` to a numeric field of the record identified
+     * by `pk`, evaluated server-side against the row's current value (e.g.
+     * `saldo = saldo + value`) — not a fetch-then-save round trip.
+     */
+    async increment(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.incrementOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "increment", options);
+    }
+    /** Same as {@link VSRepository.increment}, subtracting `value` instead of adding it. */
+    async decrement(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.decrementOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "decrement", options);
+    }
+    /** Same as {@link VSRepository.increment}, multiplying the field's current value by `value`. */
+    async multiply(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.multiplyOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "multiply", options);
+    }
+    /**
+     * Same as {@link VSRepository.increment}, dividing the field's current
+     * value by `value`. Division-by-zero behavior depends on the adapter/
+     * underlying database (see {@link VSRepoAdapter.divideOne}).
+     */
+    async divide(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.divideOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "divide", options);
+    }
+    /**
+     * Returns the sum of a numeric field across every record matching
+     * `where` (all records if omitted), or `null` if none match — mirrors
+     * SQL's `SUM()`, which returns `NULL` (not `0`) over an empty set.
+     */
+    async sum(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.sum(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "sum", options, "restrict");
+    }
+    /** Same as {@link VSRepository.sum}, but the arithmetic mean instead of the total. */
+    async average(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.average(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "average", options, "restrict");
+    }
+    /** Same as {@link VSRepository.sum}, but the minimum value instead of the total. */
+    async min(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.min(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "min", options, "restrict");
+    }
+    /** Same as {@link VSRepository.sum}, but the maximum value instead of the total. */
+    async max(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.max(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "max", options, "restrict");
     }
 }
 exports.VSRepository = VSRepository;

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,17 +3,19 @@ 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";
 export type { VSRepoMethod } from "./types/vsrepo/vsrepo-method.type.js";
-export type { VSRepoWhere, VSRepoWherePlain, VSRepoFieldWhere, VSRepoFieldOperators } from "./types/vsrepo/vsrepo-where.type.js";
+export type { VSRepoWhere, VSRepoWherePlain, VSRepoFieldWhere, VSRepoFieldOperators, } from "./types/vsrepo/vsrepo-where.type.js";
 export type { VSRepoRelations, RelationKeys } from "./types/vsrepo/vsrepo-relations.type.js";
 export type { VSRepoSelect } from "./types/vsrepo/vsrepo-select.type.js";
 export type { VSRepoTransactionOptions } from "./types/vsrepo/vsrepo-transaction-options.type.js";
@@ -31,4 +33,9 @@ export type { Pagination } from "./types/utils/pagination.type.js";
 export type { Primitive } from "./types/utils/primitive.type.js";
 export type { SeeMode } from "./types/utils/see-mode.type.js";
 export type { VSRepoQueryOptions } from "./types/vsrepo/vsrepo-query-options.type";
+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

@@ -8,6 +8,8 @@ import { Ordering } from "../../types/utils/ordering.type";
 import { VSLogger } from "../utils/vs-logger.util";
 import { VSRepoWhere } from "../../types/vsrepo/vsrepo-where.type";
 import { VSRepoQueryOptions } from "../../types/vsrepo/vsrepo-query-options.type";
+import { NumericLike } from "../../types/utils/numeric-like.type";
+import { RestrictMethodOptions } from "../../types/utils/restrict-method-options.type";
 export declare class VSRepoValidator<T, K, O extends VSRepoOrmTypes = VSRepoOrmTypes> {
     private logger?;
     setLogger(logger: VSLogger): void;
@@ -16,13 +18,15 @@ export declare class VSRepoValidator<T, K, O extends VSRepoOrmTypes = VSRepoOrmT
     validateConstructorOptions(options: unknown): VSRepoOptions<T, K>;
     private readonly methodOptionsSchema;
     validateMethodOptions(options?: unknown): MethodOptions<T, O>;
+    private readonly restrictMethodOptionsSchema;
+    validateRestrictMethodOptions(options?: unknown): RestrictMethodOptions<T, O>;
     private readonly getAllMethodOptionsSchema;
     validateGetAllMethodOptions(options?: unknown): MethodOptions<T, O> & {
         pagination?: Pagination;
         order?: Ordering<T>;
     };
     private queryArgSchema;
-    validateQueryMethodArg(arg?: unknown): QueryMethodArg<any>;
+    validateQueryMethodArg(arg?: unknown): QueryMethodArg<any[]>;
     private queryOptionsSchema;
     validateQueryOptions(options?: unknown): VSRepoQueryOptions;
     private transactionOptionsSchema;
@@ -30,4 +34,7 @@ export declare class VSRepoValidator<T, K, O extends VSRepoOrmTypes = VSRepoOrmT
     validateOrdering(value: unknown): Ordering<T>;
     validatePagination(value: unknown): Pagination;
     validateWhere(value: unknown): VSRepoWhere<T>;
+    private decimalLikeSchema;
+    private numericLikeSchema;
+    assertIsNumericLike(value: unknown): asserts value is NumericLike;
 }

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

@@ -89,6 +89,17 @@ class VSRepoValidator {
         }
         return parsed.output;
     }
+    restrictMethodOptionsSchema = v.object({
+        db: v.optional(v.any()),
+        see: v.optional(v.picklist(["active", "removed", "all"])),
+    });
+    validateRestrictMethodOptions(options) {
+        const parsed = v.safeParse(this.restrictMethodOptionsSchema, options ?? {});
+        if (!parsed.success) {
+            this.failValidation(parsed.issues[0], vsrepo_error_type_enum_1.VSRepoErrorType.VALIDATOR);
+        }
+        return parsed.output;
+    }
     getAllMethodOptionsSchema = v.object({
         ...this.methodOptionsSchema.entries,
         order: v.optional(ordering_schema_1.default),
@@ -116,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 ?? {});
@@ -156,5 +168,16 @@ class VSRepoValidator {
         }
         return parsed.output;
     }
+    decimalLikeSchema = v.looseObject({
+        toNumber: v.function(),
+        decimalPlaces: v.function(),
+    });
+    numericLikeSchema = v.union([v.number(), v.bigint(), this.decimalLikeSchema]);
+    assertIsNumericLike(value) {
+        const parsed = v.safeParse(this.numericLikeSchema, value);
+        if (!parsed.success) {
+            this.failValidation(parsed.issues[0], vsrepo_error_type_enum_1.VSRepoErrorType.VALIDATOR);
+        }
+    }
 }
 exports.VSRepoValidator = VSRepoValidator;

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/decimal-like.type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Structural shape of an arbitrary-precision "Decimal" value, as commonly
+ * returned by ORMs for `decimal`/`numeric` columns (e.g. Prisma's
+ * `Prisma.Decimal`, built on top of `decimal.js`).
+ *
+ * Matched structurally (duck-typed) instead of importing a concrete class,
+ * so the core stays ORM-agnostic — any object exposing both `toNumber()`
+ * and `decimalPlaces()` is treated as Decimal-like by {@link NumericLike}
+ * and, transitively, by {@link NumericKeys}.
+ *
+ * Note that several ORMs (e.g. Drizzle, MikroORM, TypeORM) represent
+ * `decimal`/`numeric` columns as plain `string` by default, to avoid
+ * floating-point precision loss — a `string` value does **not** satisfy
+ * `DecimalLike`. Configure the column in a numeric mode (or provide a
+ * transformer) on those ORMs if you want the field to be eligible for
+ * `increment`/`decrement`/`multiply`/`divide`/`sum`/`average`/`min`/`max`.
+ *
+ * @publicApi
+ */
+export type DecimalLike = {
+    toNumber(): number;
+    decimalPlaces(): number;
+};

package/dist/types/utils/decimal-like.type.js

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