vsrepo 1.4.0 → 2.0.0

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

@@ -0,0 +1,14 @@
+import { Ordering } from "../utils/ordering.type";
+/**
+ * Options accepted by the `@DynamicMethod` decorator.
+ *
+ * @template T Entity type the decorated method operates on.
+ *
+ * @publicApi
+ */
+export type DynamicMethodOptions<T = any> = {
+    /** Redirects the method's logic to another valid dynamic-method pattern. Useful for method names that don't follow the naming convention. */
+    proxyTo?: string;
+    /** Fixed ordering automatically injected into the query, overriding the repository's `defaultOrdering`. */
+    injectOrdering?: Ordering<T>;
+};

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

@@ -0,0 +1,15 @@
+/**
+ * Options accepted by the `@QueryMethod` decorator.
+ *
+ * @publicApi
+ */
+export type QueryMethodOptions = {
+    /**
+     * When `true`, the SQL is executed as a modifying statement (`INSERT`/`UPDATE`/`DELETE`)
+     * and the decorated method always resolves to the number of affected rows.
+     * When `false`, the SQL is executed as a read query and the method resolves
+     * to whatever return type is declared on the field.
+     * @default false
+     */
+    modifying: boolean;
+};

package/dist/types/dynamic-methods/dynamic-method-customization.type.d.ts

@@ -0,0 +1,7 @@
+export interface DynamicMethodCustomization {
+    ignoreConflicts?: boolean;
+    orderPosition?: number;
+    paginationPosition?: number;
+    injectOrdering?: object | object[];
+    distinctKeys?: string[];
+}

package/dist/types/dynamic-methods/dynamic-method-info.type.d.ts

@@ -0,0 +1,18 @@
+export type DynamicMethodInfo = {
+    onlyBaseWheres: boolean;
+    ignoreWhere: boolean;
+    ignoreOrderByAndPagination: boolean;
+    ignoreSelect: boolean;
+    ignoreIgnoreConflicts: boolean;
+    existsMode: boolean;
+    keyToMapReplaced: string;
+    argsCount: number;
+    method: string;
+    whereParams: string[];
+    otherParams: string[];
+    ignoreDistinct: boolean;
+    dataIndex?: number;
+    updateIndex?: number;
+    createIndex?: number;
+    whereIndex?: number;
+};

package/dist/types/dynamic-methods/dynamic-method-where-ops.type.d.ts

@@ -0,0 +1,6 @@
+import { VSRepoPrettyWhere } from "../vsrepo/vsrepo-pretty-where.type";
+import { VSRepoUglyWhere } from "../vsrepo/vsrepo-ugly-where.type";
+export interface DynamicMethodWhereOps {
+    uglyWheres: VSRepoUglyWhere[];
+    prettyWheres: VSRepoPrettyWhere[];
+}

package/dist/types/utils/count-result.type.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Return type of batch operations that report how many records were affected,
+ * such as `removeList`, `softRemoveList`, and `restoreList`.
+ *
+ * @publicApi
+ */
+export type CountResult = {
+    count: number;
+};

package/dist/types/utils/deep-partial.type.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Recursively makes all properties of `T` optional, including nested objects
+ * and array elements.
+ *
+ * Used to type the payloads accepted by `save`, `saveList`, and `patch`, which
+ * don't require every field of the entity to be present.
+ *
+ * @template T Type to make deeply partial.
+ *
+ * @publicApi
+ */
+export type DeepPartial<T> = T | (T extends Array<infer U> ? DeepPartial<U>[] : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T);

package/dist/types/utils/keys-of-type.type.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Extracts the keys of `T` whose value type is assignable to `K`.
+ *
+ * Used internally to constrain `pkName` to the fields of the entity that
+ * actually match the configured primary key type.
+ *
+ * @template T Object type to inspect.
+ * @template K Value type to filter by.
+ *
+ * @example
+ * ```typescript
+ * type User = { id: string; age: number; name: string };
+ * type StringKeys = KeysOfType<User, string>; // "id" | "name"
+ * ```
+ *
+ * @publicApi
+ */
+export type KeysOfType<T, K> = {
+    [P in keyof T]: T[P] extends K ? P : never;
+}[keyof T];

package/dist/types/utils/methods-options.type.d.ts

@@ -0,0 +1,23 @@
+import { SeeMode } from "./see-mode.type";
+import { VSRepoOrmTypes } from "../vsrepo/vsrepo-orm-types.type";
+import { VSRepoRelations } from "../vsrepo/vsrepo-relations.type";
+import { VSRepoSelect } from "../vsrepo/vsrepo-select.type";
+/**
+ * Options accepted by the base methods exposed by `VSRepository`
+ * (`get`, `getOrThrow`, `save`, `patch`, `remove`, etc) and by dynamic methods.
+ *
+ * @template T Entity type managed by the repository.
+ * @template K ORM type map (`dbClient`/`dbTransaction`) configured on the repository.
+ *
+ * @publicApi
+ */
+export type MethodOptions<T, K extends VSRepoOrmTypes = VSRepoOrmTypes> = {
+    /** Fields (and nested relation fields) to select in the result. */
+    select?: VSRepoSelect<T>;
+    /** Relations to eagerly load alongside the result. */
+    relations?: VSRepoRelations<T>;
+    /** Visibility mode for records with soft-delete. Defaults to `"active"`. */
+    see?: SeeMode;
+    /** Database client or transaction to run this operation in, instead of the repository's default client. */
+    db?: K["dbClient"] | K["dbTransaction"];
+};

package/dist/types/utils/ordering.type.d.ts

@@ -0,0 +1,39 @@
+import { Primitive } from "./primitive.type";
+/**
+ * Sort direction accepted by `Ordering`. Case-insensitive: both the
+ * lowercase (`"asc"`/`"desc"`) and uppercase (`"ASC"`/`"DESC"`) forms are valid.
+ *
+ * @publicApi
+ */
+export type SortDirection = "asc" | "desc" | "ASC" | "DESC";
+/**
+ * Ordering shape for a single level of an entity's fields.
+ *
+ * Scalar fields accept a `SortDirection` directly; nested object (to-one
+ * relation) fields accept a nested `Ordering`. Array (to-many relation)
+ * fields are not orderable and are excluded.
+ *
+ * @template T Entity type being ordered.
+ *
+ * @publicApi
+ */
+export type OrderByField<T> = {
+    [P in keyof T]?: NonNullable<T[P]> extends Primitive ? SortDirection : NonNullable<T[P]> extends Array<any> ? never : NonNullable<T[P]> extends object ? Ordering<NonNullable<T[P]>> : SortDirection;
+};
+/**
+ * Ordering accepted by repository methods that support `order`, such as `getAll` or a dynamic method with `Ordered`.
+ *
+ * Can be a single ordering object or a list of chained orderings, applied in
+ * the order they're declared.
+ *
+ * @template T Entity type being ordered.
+ *
+ * @example
+ * ```typescript
+ * const order: Ordering<User> = { createdAt: "desc" };
+ * const chained: Ordering<User> = [{ name: "asc" }, { createdAt: "desc" }];
+ * ```
+ *
+ * @publicApi
+ */
+export type Ordering<T> = OrderByField<T> | OrderByField<T>[];

package/dist/types/utils/pagination.type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pagination options accepted by `getAll` and by dynamic methods with `Paginated`.
+ *
+ * @publicApi
+ */
+export type Pagination = {
+    /** Maximum number of records to return. */
+    limit?: number;
+    /** Number of records to skip before starting to return results. */
+    offset?: number;
+};

package/dist/types/utils/perform-data.type.d.ts

@@ -0,0 +1,4 @@
+export type PerformData = {
+    start: number;
+    operation: string;
+};

package/dist/types/utils/primitive.type.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Types treated as scalar (non-relation) values when walking an entity's shape.
+ *
+ * @publicApi
+ */
+export type Primitive = string | number | boolean | bigint | symbol | undefined | null | Date;

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

@@ -0,0 +1,27 @@
+/**
+ * Single argument accepted by a method declared with `@QueryMethod`.
+ *
+ * `args` are injected positionally into the raw SQL statement (`$1`, `$2`, ...),
+ * allowing safe parameter injection instead of string-concatenating values
+ * directly into the query.
+ *
+ * @template T Tuple type of the positional SQL parameters, e.g. `[email: string]`.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends VSRepository<User, string> {
+ *     @QueryMethod('SELECT * FROM "user" WHERE email = $1')
+ *     declare findByEmailRaw: (arg: QueryMethodArg<[email: string]>) => Promise<User[]>;
+ * }
+ *
+ * await userRepository.findByEmailRaw({ args: ["joao@email.com"] });
+ * ```
+ *
+ * @publicApi
+ */
+export type QueryMethodArg<T extends Array<any>> = {
+    /** Positional parameters injected into the SQL placeholders (`$1`, `$2`, ...). */
+    args?: T;
+    /** Database client or transaction to run this query in, instead of the repository's default client. */
+    db?: any;
+};

package/dist/types/utils/see-mode.type.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Visibility mode for records managed by soft-delete.
+ *
+ * - `"active"` — returns only non-deleted records (default).
+ * - `"removed"` — returns only deleted records.
+ * - `"all"` — returns all records, regardless of their deletion status.
+ *
+ * Only has effect when `softRemoveKey` is configured on the repository.
+ *
+ * @publicApi
+ */
+export type SeeMode = "active" | "removed" | "all";

package/dist/types/vsrepo/vsrepo-args.type.d.ts

@@ -0,0 +1,9 @@
+import { AdapterMethodOptions } from "../adapter/adapter-method-options.type";
+import { VSRepoWhere } from "./vsrepo-where.type";
+export type VSRepoArgs<T> = {
+    where?: VSRepoWhere<T>;
+    obj?: object;
+    create?: object;
+    update?: object;
+    options?: AdapterMethodOptions<T>;
+};

package/dist/types/vsrepo/vsrepo-method.type.d.ts

@@ -0,0 +1,4 @@
+import { DynamicMethodOptions } from "../decorators/dynamic-method-options.type";
+export type VSRepoMethod<T = any> = DynamicMethodOptions<T> & {
+    propertyKey: string | symbol;
+};

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

@@ -0,0 +1,34 @@
+import { VSRepoAdapter } from "../../VSRepoAdapter";
+import { VSLogLevel } from "../../internal/enums/vs-log-level.enum";
+import { KeysOfType } from "../utils/keys-of-type.type";
+import { Ordering } from "../utils/ordering.type";
+/**
+ * Configuration passed to the `VSRepository` constructor.
+ *
+ * @template T Entity type managed by the repository.
+ * @template K Type of the entity's primary key value.
+ *
+ * @publicApi
+ */
+export type VSRepoOptions<T, K> = {
+    /** Adapter that translates the repository's operations into calls against the underlying ORM/database. */
+    adapter: VSRepoAdapter<T>;
+    /** Name of the field that represents the entity's primary key (PK). */
+    pkName: KeysOfType<T, K>;
+    /**
+     * Name of the field used for soft-delete.
+     *
+     * When configured, enables the `softRemove`, `softRemoveList`, `restore`,
+     * and `restoreList` methods.
+     */
+    softRemoveKey?: keyof T;
+    /** Minimum severity of messages printed by the repository's internal logger. Defaults to `VSLogLevel.WARN`. */
+    logLevel?: VSLogLevel;
+    /**
+     * Duration (in ms) above which a finished operation is logged as WARN
+     * instead of DEBUG, flagging potentially slow queries. Defaults to 300ms.
+     */
+    logSlowThresholdMs?: number;
+    /** Default ordering automatically applied to queries that accept `order`, unless the call overrides it. */
+    defaultOrdering?: Ordering<T>;
+};

package/dist/types/vsrepo/vsrepo-orm-types.type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Describes the ORM-specific client and transaction types a `VSRepoAdapter`
+ * (and the `VSRepository` built on top of it) works with.
+ *
+ * Implementations provide their own concrete types for `dbClient` and
+ * `dbTransaction` (e.g. `PrismaClient`/`Prisma.TransactionClient`), which
+ * `VSRepository` then uses to type `getDbClient()`, `transaction()`, and
+ * the `db` option accepted by every method.
+ *
+ * @publicApi
+ */
+export type VSRepoOrmTypes = {
+    /** Main database client type used to run queries outside a transaction. */
+    dbClient: any;
+    /** Transaction client type used to run queries inside a `transaction()` callback. */
+    dbTransaction: any;
+};

package/dist/types/vsrepo/vsrepo-pretty-where.type.d.ts

@@ -0,0 +1,7 @@
+export interface VSRepoPrettyWhere {
+    context: (string | number)[];
+    argName: string;
+    autoVal?: boolean | {} | null;
+    otherProps?: Record<string, unknown>;
+    betweenMode?: boolean;
+}

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

@@ -0,0 +1,17 @@
+import { VSRepoOrmTypes } from "./vsrepo-orm-types.type";
+/**
+ * Options accepted by `VSRepository.query()`.
+ *
+ * @publicApi
+ */
+export type VSRepoQueryOptions<T extends VSRepoOrmTypes = VSRepoOrmTypes> = {
+    /** Positional parameters injected into the SQL placeholders (`$1`, `$2`, ...). */
+    args?: any[];
+    /** Database client or transaction to run this query in, instead of the repository's default client. */
+    db?: T["dbClient"] | T["dbTransaction"];
+    /**
+     * Whether this is a modifying statement (`INSERT`/`UPDATE`/`DELETE`).
+     * @default false
+     */
+    modifying?: boolean;
+};

package/dist/types/vsrepo/vsrepo-query-options.type.js

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

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

@@ -0,0 +1,5 @@
+import { QueryMethodOptions } from "../decorators/query-method-options.type";
+export type VSRepoQuery = QueryMethodOptions & {
+    propertyKey: string | symbol;
+    value: string;
+};

package/dist/types/vsrepo/vsrepo-query.type.js

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

package/dist/types/vsrepo/vsrepo-relations.type.d.ts

@@ -0,0 +1,26 @@
+import { Primitive } from "../utils/primitive.type";
+/**
+ * Extracts the keys of `T` that represent relation fields (i.e. objects or
+ * arrays of objects, as opposed to scalar/`Primitive` fields).
+ *
+ * @template T Entity type to inspect.
+ *
+ * @publicApi
+ */
+export type RelationKeys<T> = {
+    [P in keyof T]: NonNullable<T[P]> extends Primitive ? never : NonNullable<T[P]> extends Array<infer U> ? NonNullable<U> extends Primitive ? never : P : NonNullable<T[P]> extends object ? P : never;
+}[keyof T];
+/**
+ * Shape accepted by the `relations` option of repository/adapter methods,
+ * used to eagerly load related records alongside the main result.
+ *
+ * Each relation field accepts either a `boolean` (load the relation as-is)
+ * or a nested `VSRepoRelations` to further eager-load relations of that relation.
+ *
+ * @template T Entity type being queried.
+ *
+ * @publicApi
+ */
+export type VSRepoRelations<T> = {
+    [P in RelationKeys<T>]?: NonNullable<T[P]> extends Array<infer U> ? U extends object ? boolean | VSRepoRelations<U> : boolean : NonNullable<T[P]> extends object ? boolean | VSRepoRelations<NonNullable<T[P]>> : boolean;
+};

package/dist/types/vsrepo/vsrepo-relations.type.js

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

package/dist/types/vsrepo/vsrepo-resolve-args-data.type.d.ts

@@ -0,0 +1,19 @@
+import { VSRepository } from "../../VSRepository";
+import { Pagination } from "../utils/pagination.type";
+import { MethodOptions } from "../utils/methods-options.type";
+export interface VSRepoResolveArgsData<T, K> {
+    instance: VSRepository<T, K>;
+    options: MethodOptions<T>;
+    withoutWhere?: boolean;
+    withoutSelect?: boolean;
+    specificSelect?: object;
+    specificWhere?: object;
+    dataPayload?: object;
+    createPayload?: object;
+    updatePayload?: object;
+    pagination?: Pagination;
+    ordering?: object | object[];
+    ignoreConflicts?: boolean;
+    withOrderingAndPagination?: boolean;
+    distinctKeys?: string[];
+}

package/dist/types/vsrepo/vsrepo-resolve-args-data.type.js

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

package/dist/types/vsrepo/vsrepo-select.type.d.ts

@@ -0,0 +1,15 @@
+import { Primitive } from "../utils/primitive.type";
+/**
+ * Selection shape accepted by the `select` option of repository/adapter methods.
+ *
+ * Scalar fields accept a `boolean`; relation fields accept either a `boolean`
+ * (select the relation with all of its own scalar fields) or a nested
+ * `VSRepoSelect` to further restrict which fields of the relation are returned.
+ *
+ * @template T Entity type being selected from.
+ *
+ * @publicApi
+ */
+export type VSRepoSelect<T> = {
+    [P in keyof T]?: NonNullable<T[P]> extends Primitive ? boolean : NonNullable<T[P]> extends Array<infer U> ? U extends Primitive ? boolean : VSRepoSelect<U> | boolean : NonNullable<T[P]> extends object ? VSRepoSelect<NonNullable<T[P]>> | boolean : boolean;
+};

package/dist/types/vsrepo/vsrepo-select.type.js

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

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

@@ -0,0 +1,12 @@
+import { TransactionIsolationLevel } from "../../internal/enums/transaction-isolation-level.enum";
+/**
+ * Options accepted by `VSRepository.transaction()`.
+ *
+ * @publicApi
+ */
+export type VSRepoTransactionOptions = {
+    /** Isolation level to use for the transaction. Defaults to the underlying ORM's default. */
+    isolationLevel?: TransactionIsolationLevel;
+    /** Maximum time (in ms) the transaction is allowed to run before being aborted. */
+    timeoutMs?: number;
+};

package/dist/types/vsrepo/vsrepo-transaction-options.type.js

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

package/dist/types/vsrepo/vsrepo-ugly-where.type.d.ts

@@ -0,0 +1,9 @@
+export type VSRepoUglyWhere = {
+    pushProperty: string;
+    autoInjectVal?: boolean | {} | null;
+    properties?: {
+        ignoreCase?: boolean;
+    };
+    betweenMode?: boolean;
+    name: string;
+};

package/dist/types/vsrepo/vsrepo-ugly-where.type.js

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

package/dist/types/vsrepo/vsrepo-where.type.d.ts

@@ -0,0 +1,99 @@
+import { Primitive } from "../utils/primitive.type";
+/**
+ * Operators available to filter a single scalar field's value.
+ *
+ * The set of operators offered narrows based on `V`'s type: numbers and dates
+ * additionally get `between`; strings additionally get `contains`, `startsWith`,
+ * `endsWith`, and `ignoreCase`; every non-boolean type additionally gets
+ * `in`, `notIn`, `gt`, `gte`, `lt`, and `lte`.
+ *
+ * @template V Type of the field's value.
+ *
+ * @publicApi
+ */
+export type VSRepoFieldOperators<V> = {
+    /** Matches records where the field equals `V`. */
+    equals?: V;
+    /** Negates the given value or operator object. */
+    not?: V | VSRepoFieldOperators<V>;
+} & (V extends number | Date ? {
+    /** Matches records where the field is between the given `[min, max]` tuple, inclusive. */
+    between?: [V, V];
+} : {}) & (V extends string ? {
+    /** Matches records where the field contains the given substring. */
+    contains?: string;
+    /** Matches records where the field starts with the given substring. */
+    startsWith?: string;
+    /** Matches records where the field ends with the given substring. */
+    endsWith?: string;
+    /** Applies the string filters above case-insensitively. */
+    ignoreCase?: boolean;
+} : {}) & (V extends boolean ? {} : {
+    /** Matches records where the field is one of the given values. */
+    in?: V[];
+    /** Matches records where the field is none of the given values. */
+    notIn?: V[];
+    /** Matches records where the field is greater than the given value. */
+    gt?: V;
+    /** Matches records where the field is greater than or equal to the given value. */
+    gte?: V;
+    /** Matches records where the field is less than the given value. */
+    lt?: V;
+    /** Matches records where the field is less than or equal to the given value. */
+    lte?: V;
+});
+/**
+ * Value accepted for a single scalar field in a `VSRepoWhere`/`VSRepoWherePlain`
+ * filter: either a direct value (shorthand for `equals`) or a `VSRepoFieldOperators` object.
+ *
+ * @template V Type of the field's value.
+ *
+ * @publicApi
+ */
+export type VSRepoFieldWhere<V> = V | VSRepoFieldOperators<V>;
+/**
+ * Field-level filters for an entity, without the top-level `AND`/`OR`/`NOT`
+ * logical operators (see `VSRepoWhere` for those).
+ *
+ * Scalar fields accept a `VSRepoFieldWhere`. To-many relation fields accept
+ * `_some`/`_every`/`_none` filters, applied to the related records. To-one
+ * relation fields accept `_with`/`_without` filters.
+ *
+ * @template T Entity type being filtered.
+ *
+ * @publicApi
+ */
+export type VSRepoWherePlain<T> = {
+    [P in keyof T]?: NonNullable<T[P]> extends Primitive ? VSRepoFieldWhere<T[P]> : NonNullable<T[P]> extends Array<infer U> ? U extends object ? {
+        /** Matches records where at least one related record matches the given filter. */
+        _some?: VSRepoWherePlain<U>;
+        /** Matches records where every related record matches the given filter. */
+        _every?: VSRepoWherePlain<U>;
+        /** Matches records where no related record matches the given filter. */
+        _none?: VSRepoWherePlain<U>;
+    } : VSRepoFieldWhere<T[P]> : NonNullable<T[P]> extends object ? {
+        /** Matches records whose related record matches the given filter. */
+        _with?: VSRepoWherePlain<NonNullable<T[P]>>;
+        /** Matches records whose related record does not match the given filter. */
+        _without?: VSRepoWherePlain<NonNullable<T[P]>>;
+    } : VSRepoFieldWhere<T[P]>;
+};
+/**
+ * Filter shape accepted by the `where` clause of repository/adapter methods.
+ *
+ * Combines `VSRepoWherePlain`'s field-level filters with the top-level
+ * logical operators `AND`, `OR`, and `NOT`, each accepting either a single
+ * filter object or a list of them.
+ *
+ * @template T Entity type being filtered.
+ *
+ * @publicApi
+ */
+export type VSRepoWhere<T> = VSRepoWherePlain<T> & {
+    /** Combines multiple filters, matching records that satisfy all of them. */
+    AND?: VSRepoWherePlain<T> | VSRepoWherePlain<T>[];
+    /** Combines multiple filters, matching records that satisfy at least one of them. */
+    OR?: VSRepoWherePlain<T> | VSRepoWherePlain<T>[];
+    /** Negates one or more filters, matching records that satisfy none of them. */
+    NOT?: VSRepoWherePlain<T> | VSRepoWherePlain<T>[];
+};

package/dist/types/vsrepo/vsrepo-where.type.js

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