vsrepo 1.4.2 → 2.1.0

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamicMethod = DynamicMethod;
+const dynamic_methods_key_constant_1 = require("../internal/constants/dynamic-methods-key.constant");
+const decorators_validator_1 = require("../internal/validators/decorators.validator");
+/**
+ * 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
+ */
+function DynamicMethod(options) {
+    const validatedOptions = options
+        ? decorators_validator_1.DecoratorsValidator.validateDynamicMethodOptions(options)
+        : undefined;
+    return (target, propertyKey) => {
+        const methods = Reflect.getMetadata(dynamic_methods_key_constant_1.DYNAMIC_METHODS_KEY, target) ?? [];
+        methods.push({ ...validatedOptions, propertyKey });
+        Reflect.defineMetadata(dynamic_methods_key_constant_1.DYNAMIC_METHODS_KEY, methods, target);
+    };
+}

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

@@ -0,0 +1,27 @@
+import { 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).
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends VSRepository<User, string> {
+ *     @QueryMethod('SELECT * FROM "user" WHERE email = $1')
+ *     declare findByEmailRaw: (arg: QueryMethodArg<[email: string]>) => Promise<User[]>;
+ *
+ *     @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
+ *     declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+ * }
+ * ```
+ *
+ * @publicApi
+ */
+export declare function QueryMethod(value: string, options?: QueryMethodOptions): PropertyDecorator;

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

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryMethod = QueryMethod;
+const VSRepoError_1 = require("../errors/VSRepoError");
+const query_methods_key_constant_1 = require("../internal/constants/query-methods-key.constant");
+const vsrepo_error_type_enum_1 = require("../internal/enums/vsrepo-error-type.enum");
+const decorators_validator_1 = require("../internal/validators/decorators.validator");
+/**
+ * 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).
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends VSRepository<User, string> {
+ *     @QueryMethod('SELECT * FROM "user" WHERE email = $1')
+ *     declare findByEmailRaw: (arg: QueryMethodArg<[email: string]>) => Promise<User[]>;
+ *
+ *     @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
+ *     declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+ * }
+ * ```
+ *
+ * @publicApi
+ */
+function QueryMethod(value, options) {
+    if (typeof value !== "string") {
+        throw new VSRepoError_1.VSRepoError(`'value' must be a valid string`, vsrepo_error_type_enum_1.VSRepoErrorType.DECORATOR);
+    }
+    const validatedConfig = options
+        ? decorators_validator_1.DecoratorsValidator.validateQueryMethodOptions(options)
+        : { modifying: false };
+    return (target, propertyKey) => {
+        const methods = Reflect.getMetadata(query_methods_key_constant_1.QUERY_METHODS_KEY, target) ?? [];
+        methods.push({ ...validatedConfig, value, propertyKey });
+        Reflect.defineMetadata(query_methods_key_constant_1.QUERY_METHODS_KEY, methods, target);
+    };
+}

package/dist/errors/VSRepoAdapterError.d.ts

@@ -0,0 +1,22 @@
+import { AdapterErrorCode } from "../internal/enums/adapter-error-code.enum";
+import { VSRepoError } from "./VSRepoError";
+/**
+ * Error raised when a `VSRepoAdapter` fails while talking to the underlying
+ * ORM/database. Carries a stable, adapter-agnostic {@link AdapterErrorCode} plus
+ * the original error thrown by the adapter, so callers can react to failures
+ * without depending on any specific ORM's error shape.
+ *
+ * @publicApi
+ */
+export declare class VSRepoAdapterError extends VSRepoError {
+    readonly code: AdapterErrorCode;
+    readonly originalError: unknown;
+    /**
+     * @param message - Human-readable description of the adapter failure.
+     * @param code - Stable, adapter-agnostic code classifying the failure.
+     * @param originalError - The raw error (or `null`/`undefined`) thrown by the
+     * underlying ORM/database driver.
+     * @param cause - Optional root cause to chain, e.g. the originating exception.
+     */
+    constructor(message: string, code: AdapterErrorCode, originalError: unknown, cause?: unknown);
+}

package/dist/errors/VSRepoAdapterError.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VSRepoAdapterError = void 0;
+const vsrepo_error_type_enum_1 = require("../internal/enums/vsrepo-error-type.enum");
+const VSRepoError_1 = require("./VSRepoError");
+/**
+ * Error raised when a `VSRepoAdapter` fails while talking to the underlying
+ * ORM/database. Carries a stable, adapter-agnostic {@link AdapterErrorCode} plus
+ * the original error thrown by the adapter, so callers can react to failures
+ * without depending on any specific ORM's error shape.
+ *
+ * @publicApi
+ */
+class VSRepoAdapterError extends VSRepoError_1.VSRepoError {
+    code;
+    originalError;
+    /**
+     * @param message - Human-readable description of the adapter failure.
+     * @param code - Stable, adapter-agnostic code classifying the failure.
+     * @param originalError - The raw error (or `null`/`undefined`) thrown by the
+     * underlying ORM/database driver.
+     * @param cause - Optional root cause to chain, e.g. the originating exception.
+     */
+    constructor(message, code, originalError, cause) {
+        super(message, vsrepo_error_type_enum_1.VSRepoErrorType.ADAPTER, cause);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = "VSRepoAdapterError";
+    }
+}
+exports.VSRepoAdapterError = VSRepoAdapterError;

package/dist/errors/VSRepoError.d.ts

@@ -0,0 +1,15 @@
+import { VSRepoErrorType } from "../internal/enums/vsrepo-error-type.enum";
+/**
+ * Base error thrown by VSRepository for any invalid usage, configuration, or
+ * runtime failure — decorator misuse, invalid method options, resolver
+ * failures, and base-method guard clauses.
+ *
+ * @publicApi
+ */
+export declare class VSRepoError extends Error {
+    /** Category of the error. See `VSRepoErrorType` for the full list. */
+    readonly type: VSRepoErrorType;
+    constructor(message: string, 
+    /** Category of the error. See `VSRepoErrorType` for the full list. */
+    type: VSRepoErrorType, cause?: unknown);
+}

package/dist/errors/VSRepoError.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VSRepoError = void 0;
+/**
+ * Base error thrown by VSRepository for any invalid usage, configuration, or
+ * runtime failure — decorator misuse, invalid method options, resolver
+ * failures, and base-method guard clauses.
+ *
+ * @publicApi
+ */
+class VSRepoError extends Error {
+    type;
+    constructor(message, 
+    /** Category of the error. See `VSRepoErrorType` for the full list. */
+    type, cause) {
+        super(`[VSRepository] Error: ${message}`, { cause });
+        this.type = type;
+        this.name = "VSRepoError";
+    }
+}
+exports.VSRepoError = VSRepoError;

package/dist/index.d.ts

@@ -1 +1,38 @@
-export * from "./VSRepository";
+import "reflect-metadata";
+export { VSRepository } from "./VSRepository.js";
+export { VSRepoAdapter } from "./VSRepoAdapter.js";
+export { VSRepoError } from "./errors/VSRepoError.js";
+export { VSRepoAdapterError } from "./errors/VSRepoAdapterError.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 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 { 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";
+export type { AdapterMethodOptions } from "./types/adapter/adapter-method-options.type.js";
+export type { AdapterQueryOptions } from "./types/adapter/adapter-query-options.type.js";
+export type { DynamicMethodOptions } from "./types/decorators/dynamic-method-options.type.js";
+export type { QueryMethodOptions } from "./types/decorators/query-method-options.type.js";
+export type { QueryMethodArg } from "./types/utils/query-method-arg.type.js";
+export type { CountResult } from "./types/utils/count-result.type.js";
+export type { DeepPartial } from "./types/utils/deep-partial.type.js";
+export type { KeysOfType } from "./types/utils/keys-of-type.type.js";
+export type { MethodOptions } from "./types/utils/methods-options.type.js";
+export type { Ordering, OrderByField, SortDirection } from "./types/utils/ordering.type.js";
+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 { VSLogger } from "./internal/utils/vs-logger.util.js";

package/dist/index.js

@@ -1,17 +1,30 @@
 "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 });
-__exportStar(require("./VSRepository"), exports);
+exports.VSLogger = exports.AdapterErrorCode = exports.TransactionIsolationLevel = exports.VSLogLevel = exports.VSRepoErrorType = exports.QueryMethod = exports.DynamicMethod = exports.VSRepoAdapterError = exports.VSRepoError = exports.VSRepoAdapter = exports.VSRepository = void 0;
+require("reflect-metadata");
+// Public classes / constructors
+var VSRepository_js_1 = require("./VSRepository.js");
+Object.defineProperty(exports, "VSRepository", { enumerable: true, get: function () { return VSRepository_js_1.VSRepository; } });
+var VSRepoAdapter_js_1 = require("./VSRepoAdapter.js");
+Object.defineProperty(exports, "VSRepoAdapter", { enumerable: true, get: function () { return VSRepoAdapter_js_1.VSRepoAdapter; } });
+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; } });
+// 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; } });
+var query_method_decorator_js_1 = require("./decorators/query-method.decorator.js");
+Object.defineProperty(exports, "QueryMethod", { enumerable: true, get: function () { return query_method_decorator_js_1.QueryMethod; } });
+// Public enums
+var vsrepo_error_type_enum_js_1 = require("./internal/enums/vsrepo-error-type.enum.js");
+Object.defineProperty(exports, "VSRepoErrorType", { enumerable: true, get: function () { return vsrepo_error_type_enum_js_1.VSRepoErrorType; } });
+var vs_log_level_enum_js_1 = require("./internal/enums/vs-log-level.enum.js");
+Object.defineProperty(exports, "VSLogLevel", { enumerable: true, get: function () { return vs_log_level_enum_js_1.VSLogLevel; } });
+var transaction_isolation_level_enum_js_1 = require("./internal/enums/transaction-isolation-level.enum.js");
+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; } });
+// 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/constants/debug-arg-symbol.constant.d.ts

@@ -0,0 +1 @@
+export declare const DEBUG_ARG_SYMBOL: unique symbol;

package/dist/internal/constants/debug-arg-symbol.constant.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEBUG_ARG_SYMBOL = void 0;
+exports.DEBUG_ARG_SYMBOL = Symbol("DEBUG_ARG_SYMBOL");

package/dist/internal/constants/dynamic-methods-key.constant.d.ts

@@ -0,0 +1 @@
+export declare const DYNAMIC_METHODS_KEY: unique symbol;

package/dist/internal/constants/query-methods-key.constant.d.ts

@@ -0,0 +1 @@
+export declare const QUERY_METHODS_KEY: unique symbol;

package/dist/internal/constants/query-methods-key.constant.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUERY_METHODS_KEY = void 0;
+exports.QUERY_METHODS_KEY = Symbol("query-methods-key");

package/dist/internal/enums/adapter-error-code.enum.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Granular error codes that a `VSRepoAdapter` can raise via `VSRepoAdapterError`,
+ * mirroring the most common failures thrown by ORMs and database drivers so they
+ * can be mapped to a stable, adapter-agnostic code.
+ *
+ * @publicApi
+ */
+export declare enum AdapterErrorCode {
+    /**
+     * A unknown/unclassified error raised by the underlying database or ORM.
+     * Fallback code when no more specific code matches.
+     */
+    UNKNOWN = "UNKNOWN",
+    /**
+     * The database client (or connection pool) backing the adapter was not
+     * provided or could not be resolved.
+     */
+    MISSING_DB_CLIENT = "MISSING_DB_CLIENT",
+    /**
+     * The adapter could not reach/connect to the database, or an established
+     * connection was lost/terminated.
+     */
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    /**
+     * The connection pool is exhausted or depleted: no connection was available
+     * because they were all busy or the configured limit was reached.
+     */
+    CONNECTION_POOL_EXHAUSTED = "CONNECTION_POOL_EXHAUSTED",
+    /**
+     * The database did not respond in time; a connection/query/statement
+     * exceeded its allowed timeout.
+     */
+    TIMEOUT = "TIMEOUT",
+    /**
+     * The operation violated a unique constraint (duplicate key).
+     * E.g. Postgres/SQLite `23505`, MySQL `1062`.
+     */
+    UNIQUE_CONSTRAINT_VIOLATION = "UNIQUE_CONSTRAINT_VIOLATION",
+    /** A foreign key constraint was violated (referenced row missing). */
+    FOREIGN_KEY_VIOLATION = "FOREIGN_KEY_VIOLATION",
+    /** A NOT NULL constraint was violated. */
+    NOT_NULL_VIOLATION = "NOT_NULL_VIOLATION",
+    /** A CHECK constraint was violated. */
+    CHECK_VIOLATION = "CHECK_VIOLATION",
+    /** A general integrity/constraint violation not covered by more specific codes. */
+    CONSTRAINT_VIOLATION = "CONSTRAINT_VIOLATION",
+    /** The requested record was not found (e.g. a `findOneOrThrow`-style operation). */
+    NOT_FOUND = "NOT_FOUND",
+    /**
+     * The value(s) provided for a field are invalid for its type or length, or a
+     * required value is missing.
+     */
+    INVALID_DATA = "INVALID_DATA",
+    /**
+     * The provided value is too long and exceeds the column/field length limit.
+     */
+    VALUE_TOO_LONG = "VALUE_TOO_LONG",
+    /**
+     * A value could not be converted/cast to the target type.
+     * E.g. Postgres `22P02` invalid text representation, MySQL `1366` incorrect value.
+     */
+    CONVERSION_ERROR = "CONVERSION_ERROR",
+    /** The query/stored procedure SQL is malformed or invalid. */
+    INVALID_QUERY = "INVALID_QUERY",
+    /** The referenced table/column/relation does not exist. */
+    TABLE_OR_COLUMN_NOT_FOUND = "TABLE_OR_COLUMN_NOT_FOUND",
+    /**
+     * The operation was aborted by a lock timeout or a deadlock between
+     * concurrent transactions.
+     */
+    DEADLOCK = "DEADLOCK",
+    /** The operation could not acquire a required database lock in time. */
+    LOCK_TIMEOUT = "LOCK_TIMEOUT",
+    /** The record is locked and cannot be modified. */
+    LOCKED = "LOCKED",
+    /** The current user/role does not have permission to perform the operation. */
+    ACCESS_DENIED = "ACCESS_DENIED",
+    /** Invalid connection credentials (host/user/password) provided. */
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    /** The authenticated user does not own the record / row-level security rejected it. */
+    ROW_NOT_ALLOWED = "ROW_NOT_ALLOWED",
+    /**
+     * The entity/model or table is not defined/mapped in the ORM, or the adapter
+     * lacks the model metadata to build the query.
+     */
+    MODEL_NOT_FOUND = "MODEL_NOT_FOUND",
+    /**
+     * A field/column name in the provided data or `where` does not exist on the
+     * entity/model.
+     */
+    FIELD_NOT_FOUND = "FIELD_NOT_FOUND",
+    /** A transaction was used after it was committed/rolled back. */
+    TRANSACTION_CLOSED = "TRANSACTION_CLOSED",
+    /** A nested transaction could not be opened (e.g. nested `transaction()` calls). */
+    TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
+    /** A transaction failed to commit (e.g. due to a write conflict) and was rolled back. */
+    TRANSACTION_CONFLICT = "TRANSACTION_CONFLICT",
+    /** No active transaction when one was required for the operation. */
+    TRANSACTION_NOT_STARTED = "TRANSACTION_NOT_STARTED",
+    /**
+     * The connection was closed/terminated while a transaction or query was
+     * still in progress.
+     */
+    CONNECTION_CLOSED = "CONNECTION_CLOSED",
+    /**
+     * The value provided to a `merge`/`upsert`/`update` is a partial object but
+     * is invalid or missing required keys.
+     */
+    INVALID_PARTIAL = "INVALID_PARTIAL",
+    /**
+     * An unsupported feature/operation was requested from the adapter (e.g. raw
+     * `query()` not supported by the underlying ORM).
+     */
+    NOT_SUPPORTED = "NOT_SUPPORTED",
+    /**
+     * The adapter configuration provided is invalid or incomplete (e.g. missing
+     * required options, or options with an invalid type/value).
+     */
+    INVALID_ADAPTER_CONFIG = "INVALID_ADAPTER_CONFIG",
+    /**
+     * An internal adapter bug or an unrecoverable state occurred. Should rarely
+     * be used; prefer a more specific code.
+     */
+    INTERNAL = "INTERNAL"
+}

package/dist/internal/enums/adapter-error-code.enum.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterErrorCode = void 0;
+/**
+ * Granular error codes that a `VSRepoAdapter` can raise via `VSRepoAdapterError`,
+ * mirroring the most common failures thrown by ORMs and database drivers so they
+ * can be mapped to a stable, adapter-agnostic code.
+ *
+ * @publicApi
+ */
+var AdapterErrorCode;
+(function (AdapterErrorCode) {
+    /**
+     * A unknown/unclassified error raised by the underlying database or ORM.
+     * Fallback code when no more specific code matches.
+     */
+    AdapterErrorCode["UNKNOWN"] = "UNKNOWN";
+    /**
+     * The database client (or connection pool) backing the adapter was not
+     * provided or could not be resolved.
+     */
+    AdapterErrorCode["MISSING_DB_CLIENT"] = "MISSING_DB_CLIENT";
+    /**
+     * The adapter could not reach/connect to the database, or an established
+     * connection was lost/terminated.
+     */
+    AdapterErrorCode["CONNECTION_FAILED"] = "CONNECTION_FAILED";
+    /**
+     * The connection pool is exhausted or depleted: no connection was available
+     * because they were all busy or the configured limit was reached.
+     */
+    AdapterErrorCode["CONNECTION_POOL_EXHAUSTED"] = "CONNECTION_POOL_EXHAUSTED";
+    /**
+     * The database did not respond in time; a connection/query/statement
+     * exceeded its allowed timeout.
+     */
+    AdapterErrorCode["TIMEOUT"] = "TIMEOUT";
+    /**
+     * The operation violated a unique constraint (duplicate key).
+     * E.g. Postgres/SQLite `23505`, MySQL `1062`.
+     */
+    AdapterErrorCode["UNIQUE_CONSTRAINT_VIOLATION"] = "UNIQUE_CONSTRAINT_VIOLATION";
+    /** A foreign key constraint was violated (referenced row missing). */
+    AdapterErrorCode["FOREIGN_KEY_VIOLATION"] = "FOREIGN_KEY_VIOLATION";
+    /** A NOT NULL constraint was violated. */
+    AdapterErrorCode["NOT_NULL_VIOLATION"] = "NOT_NULL_VIOLATION";
+    /** A CHECK constraint was violated. */
+    AdapterErrorCode["CHECK_VIOLATION"] = "CHECK_VIOLATION";
+    /** A general integrity/constraint violation not covered by more specific codes. */
+    AdapterErrorCode["CONSTRAINT_VIOLATION"] = "CONSTRAINT_VIOLATION";
+    /** The requested record was not found (e.g. a `findOneOrThrow`-style operation). */
+    AdapterErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    /**
+     * The value(s) provided for a field are invalid for its type or length, or a
+     * required value is missing.
+     */
+    AdapterErrorCode["INVALID_DATA"] = "INVALID_DATA";
+    /**
+     * The provided value is too long and exceeds the column/field length limit.
+     */
+    AdapterErrorCode["VALUE_TOO_LONG"] = "VALUE_TOO_LONG";
+    /**
+     * A value could not be converted/cast to the target type.
+     * E.g. Postgres `22P02` invalid text representation, MySQL `1366` incorrect value.
+     */
+    AdapterErrorCode["CONVERSION_ERROR"] = "CONVERSION_ERROR";
+    /** The query/stored procedure SQL is malformed or invalid. */
+    AdapterErrorCode["INVALID_QUERY"] = "INVALID_QUERY";
+    /** The referenced table/column/relation does not exist. */
+    AdapterErrorCode["TABLE_OR_COLUMN_NOT_FOUND"] = "TABLE_OR_COLUMN_NOT_FOUND";
+    /**
+     * The operation was aborted by a lock timeout or a deadlock between
+     * concurrent transactions.
+     */
+    AdapterErrorCode["DEADLOCK"] = "DEADLOCK";
+    /** The operation could not acquire a required database lock in time. */
+    AdapterErrorCode["LOCK_TIMEOUT"] = "LOCK_TIMEOUT";
+    /** The record is locked and cannot be modified. */
+    AdapterErrorCode["LOCKED"] = "LOCKED";
+    /** The current user/role does not have permission to perform the operation. */
+    AdapterErrorCode["ACCESS_DENIED"] = "ACCESS_DENIED";
+    /** Invalid connection credentials (host/user/password) provided. */
+    AdapterErrorCode["INVALID_CREDENTIALS"] = "INVALID_CREDENTIALS";
+    /** The authenticated user does not own the record / row-level security rejected it. */
+    AdapterErrorCode["ROW_NOT_ALLOWED"] = "ROW_NOT_ALLOWED";
+    /**
+     * The entity/model or table is not defined/mapped in the ORM, or the adapter
+     * lacks the model metadata to build the query.
+     */
+    AdapterErrorCode["MODEL_NOT_FOUND"] = "MODEL_NOT_FOUND";
+    /**
+     * A field/column name in the provided data or `where` does not exist on the
+     * entity/model.
+     */
+    AdapterErrorCode["FIELD_NOT_FOUND"] = "FIELD_NOT_FOUND";
+    /** A transaction was used after it was committed/rolled back. */
+    AdapterErrorCode["TRANSACTION_CLOSED"] = "TRANSACTION_CLOSED";
+    /** A nested transaction could not be opened (e.g. nested `transaction()` calls). */
+    AdapterErrorCode["TRANSACTION_ALREADY_STARTED"] = "TRANSACTION_ALREADY_STARTED";
+    /** A transaction failed to commit (e.g. due to a write conflict) and was rolled back. */
+    AdapterErrorCode["TRANSACTION_CONFLICT"] = "TRANSACTION_CONFLICT";
+    /** No active transaction when one was required for the operation. */
+    AdapterErrorCode["TRANSACTION_NOT_STARTED"] = "TRANSACTION_NOT_STARTED";
+    /**
+     * The connection was closed/terminated while a transaction or query was
+     * still in progress.
+     */
+    AdapterErrorCode["CONNECTION_CLOSED"] = "CONNECTION_CLOSED";
+    /**
+     * The value provided to a `merge`/`upsert`/`update` is a partial object but
+     * is invalid or missing required keys.
+     */
+    AdapterErrorCode["INVALID_PARTIAL"] = "INVALID_PARTIAL";
+    /**
+     * An unsupported feature/operation was requested from the adapter (e.g. raw
+     * `query()` not supported by the underlying ORM).
+     */
+    AdapterErrorCode["NOT_SUPPORTED"] = "NOT_SUPPORTED";
+    /**
+     * The adapter configuration provided is invalid or incomplete (e.g. missing
+     * required options, or options with an invalid type/value).
+     */
+    AdapterErrorCode["INVALID_ADAPTER_CONFIG"] = "INVALID_ADAPTER_CONFIG";
+    /**
+     * An internal adapter bug or an unrecoverable state occurred. Should rarely
+     * be used; prefer a more specific code.
+     */
+    AdapterErrorCode["INTERNAL"] = "INTERNAL";
+})(AdapterErrorCode || (exports.AdapterErrorCode = AdapterErrorCode = {}));

package/dist/internal/enums/transaction-isolation-level.enum.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Isolation levels accepted by `VSRepository.transaction()`, mirroring the
+ * standard SQL isolation levels.
+ *
+ * @publicApi
+ */
+export declare enum TransactionIsolationLevel {
+    /** Allows dirty reads: a transaction may see uncommitted changes from other transactions. */
+    READ_UNCOMMITTED = "ReadUncommitted",
+    /** Prevents dirty reads; non-repeatable reads and phantom reads may still occur. */
+    READ_COMMITTED = "ReadCommitted",
+    /** Prevents dirty and non-repeatable reads; phantom reads may still occur. */
+    REPEATABLE_READ = "RepeatableRead",
+    /** Strongest isolation level: transactions behave as if executed sequentially. */
+    SERIALIZABLE = "Serializable"
+}

package/dist/internal/enums/transaction-isolation-level.enum.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionIsolationLevel = void 0;
+/**
+ * Isolation levels accepted by `VSRepository.transaction()`, mirroring the
+ * standard SQL isolation levels.
+ *
+ * @publicApi
+ */
+var TransactionIsolationLevel;
+(function (TransactionIsolationLevel) {
+    /** Allows dirty reads: a transaction may see uncommitted changes from other transactions. */
+    TransactionIsolationLevel["READ_UNCOMMITTED"] = "ReadUncommitted";
+    /** Prevents dirty reads; non-repeatable reads and phantom reads may still occur. */
+    TransactionIsolationLevel["READ_COMMITTED"] = "ReadCommitted";
+    /** Prevents dirty and non-repeatable reads; phantom reads may still occur. */
+    TransactionIsolationLevel["REPEATABLE_READ"] = "RepeatableRead";
+    /** Strongest isolation level: transactions behave as if executed sequentially. */
+    TransactionIsolationLevel["SERIALIZABLE"] = "Serializable";
+})(TransactionIsolationLevel || (exports.TransactionIsolationLevel = TransactionIsolationLevel = {}));

package/dist/internal/enums/vs-log-level.enum.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimum severity a message must have to be printed by the repository's
+ * internal logger, configured via `VSRepoOptions.logLevel`. Levels are
+ * ordered from most to least verbose; setting a level suppresses all
+ * messages below it.
+ *
+ * @publicApi
+ */
+export declare enum VSLogLevel {
+    /** Verbose internal details, including every resolved query. */
+    DEBUG = 0,
+    /** High-level lifecycle events, such as repository initialization. */
+    INFO = 1,
+    /** Recoverable issues and slow operations (see `logSlowThresholdMs`). */
+    WARN = 2,
+    /** Failures raised while executing an operation. */
+    ERROR = 3
+}

package/dist/internal/enums/vs-log-level.enum.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VSLogLevel = void 0;
+/**
+ * Minimum severity a message must have to be printed by the repository's
+ * internal logger, configured via `VSRepoOptions.logLevel`. Levels are
+ * ordered from most to least verbose; setting a level suppresses all
+ * messages below it.
+ *
+ * @publicApi
+ */
+var VSLogLevel;
+(function (VSLogLevel) {
+    /** Verbose internal details, including every resolved query. */
+    VSLogLevel[VSLogLevel["DEBUG"] = 0] = "DEBUG";
+    /** High-level lifecycle events, such as repository initialization. */
+    VSLogLevel[VSLogLevel["INFO"] = 1] = "INFO";
+    /** Recoverable issues and slow operations (see `logSlowThresholdMs`). */
+    VSLogLevel[VSLogLevel["WARN"] = 2] = "WARN";
+    /** Failures raised while executing an operation. */
+    VSLogLevel[VSLogLevel["ERROR"] = 3] = "ERROR";
+})(VSLogLevel || (exports.VSLogLevel = VSLogLevel = {}));