vsrepo 1.4.2 → 2.1.0

package/dist/VSRepository.js

@@ -1,245 +1,335 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setupVSRepo = exports.VSRepository = void 0;
-__exportStar(require("./internal/errors/vs-repo.error"), exports);
-const build_config_validate_1 = require("./internal/validation/build-config.validate");
-const constructor_config_validate_1 = require("./internal/validation/constructor-config.validate");
-const extension_validate_1 = require("./internal/validation/extension.validate");
-const prisma_client_validate_1 = require("./internal/validation/prisma-client.validate");
-const vs_repo_error_1 = require("./internal/errors/vs-repo.error");
-const base_methods_resolve_1 = require("./internal/resolvers/base-methods.resolve");
-const logger_util_1 = require("./internal/utils/logger.util");
-const dynamic_method_info_resolve_1 = require("./internal/resolvers/dynamic-method-info.resolve");
-const dynamic_method_customization_resolve_1 = require("./internal/resolvers/dynamic-method-customization.resolve");
-const pretty_wheres_resolve_1 = require("./internal/resolvers/pretty-wheres.resolve");
-const specific_where_resolve_1 = require("./internal/resolvers/specific-where.resolve");
-const dbAndPrismaArgs_resolve_1 = require("./internal/resolvers/dbAndPrismaArgs.resolve");
-const method_options_validate_1 = require("./internal/validation/method-options.validate");
-const query_method_arg_validate_1 = require("./internal/validation/query-method-arg.validate");
+exports.VSRepository = void 0;
+require("reflect-metadata");
+const merge_wheres_resolver_1 = require("./internal/resolvers/merge-wheres.resolver");
+const vs_logger_util_1 = require("./internal/utils/vs-logger.util");
+const vs_log_level_enum_1 = require("./internal/enums/vs-log-level.enum");
+const vsrepo_validator_1 = require("./internal/validators/vsrepo.validator");
+const dynamic_methods_resolver_1 = require("./internal/resolvers/dynamic-methods.resolver");
+const VSRepoError_1 = require("./errors/VSRepoError");
+const vsrepo_error_type_enum_1 = require("./internal/enums/vsrepo-error-type.enum");
+/**
+ * ORM-agnostic base repository, exposing a complete set of ready-to-use CRUD
+ * and soft-delete methods around an entity, plus any `@DynamicMethod`/`@QueryMethod`
+ * decorated methods declared on the subclass.
+ *
+ * Unlike the previous (v1) `VSRepository`, this class delegates every
+ * operation to a `VSRepoAdapter` instead of talking to Prisma directly, which
+ * is what allows it to work with any ORM/database that has an adapter
+ * implementation (e.g. Prisma, TypeORM).
+ *
+ * @template Entity Type of the entity managed by the repository.
+ * @template PKType Type of the entity's primary key value.
+ * @template OrmTypes ORM-specific client/transaction types. See `VSRepoOrmTypes`.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends VSRepository<User, string> {
+ *     constructor() {
+ *         super({ pkName: "id", adapter: new VSRepoPrisma7Adapter(prisma, "user") });
+ *     }
+ *
+ *     @DynamicMethod()
+ *     declare findByEmail: (email: string) => Promise<User[]>;
+ * }
+ *
+ * const userRepository = new UserRepository();
+ * const user = await userRepository.get("123");
+ * ```
+ *
+ * @publicApi
+ */
 class VSRepository {
-    vsrepocache;
-    tableName;
     pkName;
-    softRemovekName;
-    selectModels;
-    includeModels;
-    defaultSelectModel;
-    requiredWhere;
-    relations;
-    methods;
+    adapter;
+    mergeWheresResolver;
+    logger;
+    validator;
+    softRemoveKey;
     defaultOrdering;
-    constructor(config) {
-        const validatedConfig = (0, constructor_config_validate_1.validateConstructorConfig)(config);
-        this.vsrepocache = new Map();
-        this.tableName = validatedConfig.tableName;
-        this.pkName = validatedConfig.pkName;
-        this.softRemovekName = validatedConfig.softRemovekName;
-        this.selectModels = validatedConfig.selectModels;
-        this.includeModels = validatedConfig.includeModels;
-        this.defaultSelectModel = validatedConfig.defaultSelectModel;
-        this.relations = validatedConfig.relations;
-        this.requiredWhere = validatedConfig.requiredWhere;
-        this.methods = validatedConfig.methods;
-        this.defaultOrdering = validatedConfig.defaultOrdering;
-    }
-    extend(extensionFunc) {
-        const extension = (0, extension_validate_1.validateExtension)(extensionFunc, this);
-        const extended = Object.assign(Object.create(this), extension);
-        if (Object.isFrozen(this)) {
-            Object.freeze(extended);
-        }
-        return extended;
-    }
-    build(prisma, config, useInstance) {
-        (0, prisma_client_validate_1.validatePrismaClient)(prisma, this);
-        const buildInstance = useInstance ?? Object.create(this);
-        buildInstance.prisma = prisma;
-        if (buildInstance.softRemovekName &&
-            prisma[buildInstance.tableName]["fields"][buildInstance.softRemovekName]["typeName"] !==
-                "DateTime") {
-            throw new vs_repo_error_1.VSRepoBuildError(`[VSRepository] (${buildInstance.tableName}: build) 'typeName' of 'softRemovekName' must be "DateTime": ${buildInstance.softRemovekName}`);
-        }
-        const validatedConfig = (0, build_config_validate_1.validateBuildConfig)(config ?? {}, buildInstance);
-        (0, base_methods_resolve_1.resolveBaseMethods)(buildInstance, validatedConfig);
-        const showWorking = validatedConfig.showWorking;
-        const methods = buildInstance.methods;
-        if (methods) {
-            const methodsToMap = Object.keys(methods).filter(m => methods[m]?.map);
-            if (showWorking)
-                (0, logger_util_1.logger)("Keys to map:", "build", buildInstance.tableName, methodsToMap);
-            for (let methodToMap of methodsToMap) {
-                const originalKey = methodToMap;
-                if (methods[originalKey]?.query) {
-                    const modifyingQueryMethod = methods[originalKey].query.modifying;
-                    const valueQueryMethod = methods[originalKey].query.value;
-                    buildInstance[originalKey] = async (arg) => {
-                        const queryArgValidated = (0, query_method_arg_validate_1.validateQueryMethodArg)(arg, buildInstance);
-                        const db = queryArgValidated.db ?? buildInstance.prisma;
-                        const start = showWorking
-                            ? (0, logger_util_1.performanceLoggerStart)(buildInstance.tableName, `Query method: ${originalKey} (Modifying: ${modifyingQueryMethod})`, queryArgValidated.args)
-                            : undefined;
-                        try {
-                            const result = await db[modifyingQueryMethod ? "$executeRawUnsafe" : "$queryRawUnsafe"](valueQueryMethod, ...queryArgValidated.args);
-                            if (showWorking)
-                                (0, logger_util_1.performanceLoggerEnd)(buildInstance.tableName, `Query method: ${originalKey} (Modifying: ${modifyingQueryMethod})`, start);
-                            return result;
-                        }
-                        catch (err) {
-                            throw err;
-                        }
-                    };
-                    continue;
-                }
-                methodToMap = methods[originalKey]?.proxyTo ?? methodToMap;
-                const dynamicMethodInfo = (0, dynamic_method_info_resolve_1.resolveDynamicMethodInfo)(buildInstance, methodToMap, originalKey);
-                const dynamicMethodCustomization = (0, dynamic_method_customization_resolve_1.resolveDynamicMethodCustomization)(buildInstance, dynamicMethodInfo, originalKey);
-                const dynamicMethodWhereOps = {
-                    uglyWheres: [],
-                    prettyWheres: [],
-                    whereType: methods[originalKey]?.whereType ?? "extending",
-                    pushWhere: methods[originalKey]?.pushWhere,
-                };
-                if (!dynamicMethodInfo.ignoreWhere) {
-                    (0, pretty_wheres_resolve_1.resolvePrettyWheres)(dynamicMethodInfo, dynamicMethodWhereOps);
-                    // if (showWorking) {
-                    //     const argsSimulation: any[] = [];
-                    //     for (let x = 0; x < dynamicMethodInfo.argsCount; x++) {
-                    //         argsSimulation[x] = "00";
-                    //     }
-                    //     logger(
-                    //         `Where object resolved to ${methodToMap}:`,
-                    //         "build",
-                    //         buildInstance.tableName,
-                    //         resolveSpecificWhere(
-                    //             argsSimulation,
-                    //             dynamicMethodWhereOps.prettyWheres,
-                    //         ),
-                    //     );
-                    //     // logger(
-                    //     //     `Where object resolved to ${methodToMap}:`,
-                    //     //     "build",
-                    //     //     buildInstance.tableName,
-                    //     //     dynamicMethodWhereOps.prettyWheres,
-                    //     // );
-                    // }
-                }
-                let select = undefined;
-                if (dynamicMethodInfo.existsMode) {
-                    select = { [buildInstance.pkName]: true };
-                }
-                buildInstance.vsrepocache.set(originalKey, (args, methodOptions) => {
-                    if (dynamicMethodInfo.prismaArgsIndex !== undefined)
-                        return args.at(dynamicMethodInfo.prismaArgsIndex);
-                    const resolveDbAndPrismaArgsData = {
-                        instance: buildInstance,
-                        options: methodOptions,
-                        alreadyValidatedOptions: true,
-                        baseConfig: {
-                            active: true,
-                            defaultSelect: methods[originalKey]?.selectModel,
-                            ignoreRequiredWhere: dynamicMethodWhereOps.whereType === "overwrite",
-                        },
-                        withoutWhere: dynamicMethodInfo.ignoreWhere && !dynamicMethodInfo.onlyBaseWheres,
-                        specificSelect: select,
-                        pushWhere: dynamicMethodWhereOps.pushWhere,
-                        withoutSelect: dynamicMethodInfo.ignoreSelect,
-                        skipDuplicates: dynamicMethodCustomization.skipDuplicates,
-                        ordering: dynamicMethodCustomization.orderPosition !== undefined
-                            ? args.at(dynamicMethodCustomization.orderPosition)
-                            : dynamicMethodCustomization.injectOrdering,
-                        pagination: dynamicMethodCustomization.paginationPosition !== undefined
-                            ? args.at(dynamicMethodCustomization.paginationPosition)
-                            : dynamicMethodCustomization.injectPagination,
-                        dataPayload: dynamicMethodInfo.dataIndex !== undefined
-                            ? args.at(dynamicMethodInfo.dataIndex)
-                            : undefined,
-                        createPayload: dynamicMethodInfo.createIndex !== undefined
-                            ? args.at(dynamicMethodInfo.createIndex)
-                            : undefined,
-                        updatePayload: dynamicMethodInfo.updateIndex !== undefined
-                            ? args.at(dynamicMethodInfo.updateIndex)
-                            : undefined,
-                        withOrderingAndPagination: !dynamicMethodInfo.ignoreOrderByAndPagination,
-                        distinctKeys: dynamicMethodCustomization.distinctKeys,
-                    };
-                    if (!dynamicMethodInfo.ignoreWhere) {
-                        resolveDbAndPrismaArgsData.specificWhere = (0, specific_where_resolve_1.resolveSpecificWhere)(args, dynamicMethodWhereOps.prettyWheres);
-                    }
-                    else if (dynamicMethodInfo.onlyBaseWheres) {
-                        resolveDbAndPrismaArgsData.specificWhere =
-                            dynamicMethodInfo.whereIndex !== undefined
-                                ? args.at(dynamicMethodInfo.whereIndex)
-                                : {};
-                    }
-                    const { prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)(resolveDbAndPrismaArgsData);
-                    return prismaArgs;
-                });
-                if (showWorking) {
-                    const argsSimulation = new Array(dynamicMethodInfo.argsCount).fill("00");
-                    const prismaArgs = buildInstance.vsrepocache.get(originalKey)(argsSimulation);
-                    (0, logger_util_1.logger)(`PrismaArgs preview for ${methodToMap}:`, "build", buildInstance.tableName, prismaArgs);
-                }
-                buildInstance[originalKey] = async (...args) => {
-                    let db = buildInstance.prisma;
-                    let methodOptions = undefined;
-                    if (args.length < dynamicMethodInfo.argsCount) {
-                        const missingParams = dynamicMethodInfo.whereParams
-                            .concat(dynamicMethodInfo.otherParams)
-                            .slice(args.length);
-                        throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${buildInstance.tableName}: runtime) Missing parameters: ${missingParams.join(", ")}`, "48670");
-                    }
-                    else if (args.length > dynamicMethodInfo.argsCount) {
-                        const optionsArg = args[args.length - 1];
-                        methodOptions = (0, method_options_validate_1.validateMethodOptions)(optionsArg, buildInstance);
-                        db = methodOptions.db ?? db;
-                    }
-                    else {
-                        args.push("1");
-                    }
-                    const prismaArgs = buildInstance.vsrepocache.get(originalKey)(args, methodOptions);
-                    const start = showWorking
-                        ? (0, logger_util_1.performanceLoggerStart)(buildInstance.tableName, dynamicMethodInfo.method, prismaArgs)
-                        : undefined;
-                    try {
-                        const result = await db[buildInstance.tableName][dynamicMethodInfo.method](prismaArgs);
-                        if (showWorking)
-                            (0, logger_util_1.performanceLoggerEnd)(buildInstance.tableName, dynamicMethodInfo.method, start);
-                        if (dynamicMethodInfo.existsMode) {
-                            return !!result;
-                        }
-                        return result;
-                    }
-                    catch (err) {
-                        // logger(
-                        //     `Fatal error when executing ${dynamicMethodInfo.method}:`,
-                        //     "runtime",
-                        //     buildInstance.tableName,
-                        //     { prismaArgs },
-                        // );
-                        throw err;
-                    }
-                };
-            }
-        }
-        if (validatedConfig.freeze)
-            Object.freeze(buildInstance);
-        return buildInstance;
+    /**
+     * This is a property managed by VSRepository, please don't modify it!!
+     * @internal
+     */
+    $vsrepocache = new Map();
+    /**
+     * Creates a configured instance of `VSRepository`, resolving and validating
+     * every `@DynamicMethod`/`@QueryMethod` declared on the subclass.
+     */
+    constructor(options) {
+        this.validator = new vsrepo_validator_1.VSRepoValidator();
+        const optionsValidated = this.validator.validateConstructorOptions(options);
+        this.adapter = optionsValidated.adapter;
+        this.pkName = optionsValidated.pkName;
+        this.softRemoveKey = optionsValidated.softRemoveKey;
+        this.defaultOrdering = optionsValidated.defaultOrdering;
+        this.mergeWheresResolver = new merge_wheres_resolver_1.MergeWheresResolver(this.softRemoveKey);
+        this.logger = new vs_logger_util_1.VSLogger(optionsValidated.logLevel ?? vs_log_level_enum_1.VSLogLevel.WARN, this.constructor.name + "Logger", optionsValidated.logSlowThresholdMs);
+        this.validator.setLogger(this.logger);
+        this.logger.logInfo(`Initializing ${this.constructor.name} (pk: '${String(this.pkName)}'` +
+            (this.softRemoveKey ? `, softRemoveKey: '${String(this.softRemoveKey)}'` : "") +
+            (this.defaultOrdering
+                ? `, defaultOrdering: ${JSON.stringify(this.defaultOrdering)}`
+                : "") +
+            `, adapter: ${this.adapter.constructor.name}` +
+            `)`);
+        const dynamicMethodsResolver = new dynamic_methods_resolver_1.DynamicMethodsResolver(this.logger, this.adapter, this.mergeWheresResolver, this.validator, this.defaultOrdering);
+        let dynamicMethodsCount = 0;
+        let queryMethodsCount = 0;
+        try {
+            const start = this.logger.startPerformLog("resolve dynamic methods");
+            dynamicMethodsCount = dynamicMethodsResolver.resolve(this);
+            this.logger.endPerformLog(start);
+            const startQuery = this.logger.startPerformLog("resolve query methods");
+            queryMethodsCount = dynamicMethodsResolver.resolveQueries(this);
+            this.logger.endPerformLog(startQuery);
+        }
+        catch (err) {
+            this.logger.logError(`Failed to initialize ${this.constructor.name}`, err);
+            throw err;
+        }
+        this.logger.logInfo(`${this.constructor.name} ready (${dynamicMethodsCount} dynamic method(s), ${queryMethodsCount} query method(s) resolved)`);
+    }
+    // * Loga o erro antes de lançar, pra guard clauses (mau uso da API) não passarem em silêncio
+    fail(message, type) {
+        this.logger.logError(`${this.constructor.name}: ${message}`);
+        throw new VSRepoError_1.VSRepoError(message, type);
+    }
+    wherePk(pk) {
+        return { [this.pkName]: pk };
+    }
+    wherePkIn(pks) {
+        return { [this.pkName]: { in: pks } };
+    }
+    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 {
+            const result = await fn(optionsChecked);
+            this.logger.endPerformLog(start);
+            return result;
+        }
+        catch (err) {
+            this.logger.endPerformLog(start);
+            // this.logger.logError(`Failed to run '${methodName}' on ${this.constructor.name}`, err);
+            throw err;
+        }
+    }
+    /**
+     * Runs `fn` inside a native transaction of the underlying ORM, sharing the
+     * transaction client (`tx`) across every repository call made within it.
+     */
+    async transaction(fn, options) {
+        if (typeof fn !== "function") {
+            this.fail("'fn' must be a valid function", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
+        }
+        return this.adapter.runInTransaction(fn, this.validator.validateTransactionOptions(options));
+    }
+    /** Returns the underlying ORM client instance used outside of transactions. */
+    getDbClient() {
+        return this.adapter.getDbClient();
+    }
+    /**
+     * Executes a raw query/statement directly against the underlying database.
+     *
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * const users = await userRepository.query<User[]>(
+     *     'SELECT * FROM "user" WHERE email = $1',
+     *     { args: ["joao@email.com"] },
+     * );
+     *
+     * const affected = await userRepository.query<number>(
+     *     'UPDATE "user" SET active = true WHERE id = $1',
+     *     { args: ["123"], modifying: true },
+     * );
+     * ```
+     */
+    async query(query, options) {
+        if (typeof query !== "string") {
+            this.fail("'query' must be a valid string", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
+        }
+        const optionsValidated = this.validator.validateQueryOptions(options);
+        optionsValidated.db ??= this.getDbClient();
+        const start = this.logger.startPerformLog("run query");
+        try {
+            const result = await this.adapter.query(query, {
+                args: optionsValidated.args,
+                db: optionsValidated.db,
+                modifying: optionsValidated.modifying ?? false,
+            });
+            this.logger.endPerformLog(start);
+            return result;
+        }
+        catch (err) {
+            this.logger.endPerformLog(start);
+            // this.logger.logError(`Failed to run 'query' on ${this.constructor.name}`, err);
+            throw err;
+        }
+    }
+    /** Fetches a record by its primary key (PK). */
+    async get(pk, options) {
+        return this.execBaseMethod(opt => this.adapter.findOne(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "get", options);
+    }
+    /** Fetches a record by PK and throws an Error if not found. */
+    async getOrThrow(pk, options) {
+        return this.execBaseMethod(opt => this.adapter.findOneOrThrow(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "getOrThrow", options);
+    }
+    /** Fetches multiple records by a list of primary keys (PKs). */
+    async getList(pks, options) {
+        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.findMany(this.mergeWheresResolver.resolve(opt.see, this.wherePkIn(pks)), opt), "getList", options);
+    }
+    /** Fetches all records (respects the repository's `defaultOrdering` unless `order` is provided). */
+    async getAll(options) {
+        return this.execBaseMethod((opt) => this.adapter.findMany(this.mergeWheresResolver.resolve(opt.see, {}), {
+            ...opt,
+            order: opt.order ?? this.defaultOrdering,
+        }), "getAll", options, "getAll");
+    }
+    /** Creates or updates (upsert) a record. */
+    async save(obj, options) {
+        return this.execBaseMethod(opt => this.adapter.save(obj, opt), "save", options);
+    }
+    /** Creates or updates (upsert) multiple records in a single operation. */
+    async saveList(objs, options) {
+        if (!Array.isArray(objs)) {
+            this.fail("'objs' must be a valid array", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
+        }
+        return this.execBaseMethod(opt => this.adapter.saveMany(objs, opt), "saveList", options);
+    }
+    /** Deletes a record identified by its primary key (PK). */
+    async remove(pk, options) {
+        return this.execBaseMethod(opt => this.adapter.delete(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "remove", options);
+    }
+    /** Deletes multiple records by their primary keys, returning the count of affected rows. */
+    async removeList(pks, options) {
+        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, "restrict");
+    }
+    /** Partially updates an existing record by its primary key (PK). */
+    async patch(pk, obj, options) {
+        return this.execBaseMethod(opt => this.adapter.update(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), obj, opt), "patch", options);
+    }
+    /**
+     * Fetches a record by PK and returns it deep-merged, in memory, with the
+     * provided object — does **not** persist anything (pass the result to
+     * `save`/`patch` yourself to write it).
+     */
+    async merge(pk, obj, options) {
+        return this.execBaseMethod(opt => this.adapter.merge(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), obj, opt), "merge", options);
+    }
+    /** Returns the total number of records. */
+    async 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, "restrict");
+    }
+    /** Marks a record as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
+    async softRemove(pk, options) {
+        if (!this.softRemoveKey) {
+            this.fail("this method can only be used if you have configured 'softRemoveKey' in this repository.", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
+        }
+        const key = this.softRemoveKey;
+        return this.execBaseMethod(opt => this.adapter.update(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePk(pk)), { [key]: new Date() }, opt), "softRemove", options);
+    }
+    /** Marks multiple records as deleted (soft-delete) in batch. Requires `softRemoveKey` to be configured on the repository. */
+    async softRemoveList(pks, options) {
+        if (!this.softRemoveKey) {
+            this.fail("this method can only be used if you have configured 'softRemoveKey' in this repository.", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
+        }
+        if (!Array.isArray(pks)) {
+            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, "restrict");
+    }
+    /** Restores a record previously marked as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
+    async restore(pk, options) {
+        if (!this.softRemoveKey) {
+            this.fail("this method can only be used if you have configured 'softRemoveKey' in this repository.", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
+        }
+        const key = this.softRemoveKey;
+        return this.execBaseMethod(opt => this.adapter.update(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePk(pk)), { [key]: null }, opt), "restore", options);
+    }
+    /** Restores multiple records previously marked as deleted (soft-delete) in batch. Requires `softRemoveKey` to be configured on the repository. */
+    async restoreList(pks, options) {
+        if (!this.softRemoveKey) {
+            this.fail("this method can only be used if you have configured 'softRemoveKey' in this repository.", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
+        }
+        if (!Array.isArray(pks)) {
+            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, "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;
-const setupVSRepo = () => (config) => new VSRepository(config);
-exports.setupVSRepo = setupVSRepo;

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

@@ -0,0 +1,25 @@
+import { DynamicMethodOptions } from "../types/decorators/dynamic-method-options.type";
+/**
+ * Property decorator used to declare a dynamic method on a `VSRepository` subclass.
+ *
+ * Applied to a `declare` class field whose name follows one of the supported
+ * dynamic-method patterns (e.g. `findByEmail`, `findManyByStatusPaginated`,
+ * `upsertById`), the method's behavior is inferred from the field name at
+ * construction time, optionally adjusted via `options`.
+ *
+ * @template T Entity type the decorated method operates on.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends VSRepository<User, string> {
+ *     @DynamicMethod()
+ *     declare findByEmail: (email: string) => Promise<User[]>;
+ *
+ *     @DynamicMethod<User>({ injectOrdering: { createdAt: "desc" } })
+ *     declare findByAge: (age: number) => Promise<User[]>;
+ * }
+ * ```
+ *
+ * @publicApi
+ */
+export declare function DynamicMethod<T = any>(options?: DynamicMethodOptions<T>): PropertyDecorator;