vsrepo 2.0.0 → 2.2.0

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

@@ -0,0 +1,24 @@
+import { NumericLike } from "./numeric-like.type";
+/**
+ * Extracts the keys of `T` whose (non-nullable) value type is assignable to
+ * {@link NumericLike} — i.e. the fields eligible as the `field` argument of
+ * `increment`/`decrement`/`multiply`/`divide`/`sum`/`average`/`min`/`max`.
+ *
+ * Nullable/optional numeric fields (e.g. `number | null`) ARE included —
+ * the `null`/`undefined` part is stripped before the check, it isn't a
+ * reason to exclude the field. This means a field that is currently `NULL`
+ * in the database can be targeted; be aware that in standard SQL, arithmetic
+ * against a `NULL` value (`NULL + 5`) itself stays `NULL` — this type only
+ * governs what compiles, not the row's runtime value.
+ *
+ * @example
+ * ```typescript
+ * type Product = { id: string; price: Decimal; stock: number | null; name: string };
+ * type Numeric = NumericKeys<Product>; // "price" | "stock"
+ * ```
+ *
+ * @publicApi
+ */
+export type NumericKeys<T> = {
+    [P in keyof T]: NonNullable<T[P]> extends NumericLike ? P : never;
+}[keyof T];

package/dist/types/utils/numeric-keys.type.js

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

package/dist/types/utils/numeric-like.type.d.ts

@@ -0,0 +1,10 @@
+import { DecimalLike } from "./decimal-like.type";
+/**
+ * Union of value types accepted as "numeric" by the atomic
+ * (`increment`/`decrement`/`multiply`/`divide`) and aggregate
+ * (`sum`/`average`/`min`/`max`) operations: a native `number`, a native
+ * `bigint`, or a {@link DecimalLike} object.
+ *
+ * @publicApi
+ */
+export type NumericLike = number | bigint | DecimalLike;

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

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

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

@@ -1,6 +1,7 @@
+import { DecimalLike } from "./decimal-like.type";
 /**
  * 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;
+export type Primitive = string | number | boolean | bigint | symbol | undefined | null | Date | DecimalLike;

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

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

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

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

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

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

package/dist/types/utils/restrict-method-options.type.d.ts

@@ -0,0 +1,14 @@
+import { VSRepoOrmTypes } from "../vsrepo/vsrepo-orm-types.type";
+import { MethodOptions } from "./methods-options.type";
+/**
+ * Narrowed variant of {@link MethodOptions} exposing only `db` and `see`.
+ *
+ * Used by base methods that don't shape/return an `Entity` — count-like
+ * operations (`total`, `has`, `sum`, `average`, `min`, `max`) and
+ * batch-delete-like operations (`removeList`, `softRemoveList`,
+ * `restoreList`) — where `select`/`relations` (which only make sense when
+ * an `Entity` is being returned) don't apply.
+ *
+ * @publicApi
+ */
+export type RestrictMethodOptions<T, O extends VSRepoOrmTypes = VSRepoOrmTypes> = Pick<MethodOptions<T, O>, "db" | "see">;

package/dist/types/utils/restrict-method-options.type.js

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

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

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

package/package.json

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