vsrepo 2.4.0 → 2.5.0

package/dist/types/utils/infer-method-return.type.d.ts

@@ -0,0 +1,108 @@
+import { RelationKeys } from "../vsrepo/vsrepo-relations.type";
+import { SeeMode } from "./see-mode.type";
+/**
+ * Loose structural constraint for the `Options` accepted by {@link InferMethodReturn}.
+ * Mirrors the four keys of `MethodOptions` without depending on the entity type.
+ */
+type InferMethodReturnOptions = {
+    select?: object | undefined;
+    relations?: object | undefined;
+    see?: SeeMode | undefined;
+    db?: unknown;
+};
+/** Flattens an intersection into a single object type (keeps modifiers). */
+type Simplify<X> = {
+    [K in keyof X]: X[K];
+} & {};
+/** Safe `O[K]`: `undefined` when `K` is not a key of `O`. */
+type Get<O, K extends string> = K extends keyof O ? O[K] : undefined;
+/**
+ * How a given option (`select`/`relations`) was typed:
+ * - `"absent"`  — not provided (or explicitly `undefined`);
+ * - `"unknown"` — declared but not narrowed (optional/wide, e.g. a variable annotated as
+ *                 plain `MethodOptions<T>`), so its contents can't be known at compile time;
+ * - `"known"`   — a narrowed object type (e.g. `{ id: true }` obtained via `satisfies`).
+ */
+type OptionState<O, K extends string> = [Get<O, K>] extends [undefined] ? "absent" : undefined extends Get<O, K> ? "unknown" : "known";
+/** Keys present in a `select`/`relations` spec (`undefined` spec has none). */
+type SpecKeys<S> = S extends object ? keyof S : never;
+/**
+ * Nested spec of key `K` inside `S`: the object itself when it's a nested
+ * `select`/`relations`, or `undefined` when the value is just `true`.
+ */
+type SubSpec<S, K> = S extends object ? K extends keyof S ? NonNullable<S[K]> extends object ? NonNullable<S[K]> : undefined : undefined : undefined;
+/** Keys of `T` that are scalar fields (i.e. not relations). */
+type ScalarKeys<T> = Exclude<keyof T, RelationKeys<T>>;
+/** Which option is currently driving the shape. */
+type SpecMode = "select" | "relations";
+/** Scalar keys kept in the result: only the ones in a `select` spec, all of them otherwise. */
+type ResultScalarKeys<T, Spec, Mode extends SpecMode> = Mode extends "select" ? Spec extends object ? Extract<SpecKeys<Spec>, ScalarKeys<T>> : ScalarKeys<T> : ScalarKeys<T>;
+/** Relation keys kept in the result: the relation keys present in the spec. */
+type ResultRelationKeys<T, Spec> = Extract<SpecKeys<Spec>, RelationKeys<T>>;
+/** Applies the shape to a relation field, preserving its array-ness and nullability. */
+type MapRelation<F, Spec, Mode extends SpecMode> = F extends readonly (infer U)[] ? Shape<U, Spec, Mode>[] : F extends null | undefined ? F : Shape<F, Spec, Mode>;
+/**
+ * Shape of a single entity `T` given a `select` spec (`Mode = "select"`) or
+ * a `relations` spec (`Mode = "relations"`).
+ *
+ * - `select` mode: only the fields present in the spec; a relation set to `true` brings all of
+ *   its scalar fields (no nested relations), a nested object restricts it further.
+ * - `relations` mode: every scalar field plus the relations present in the spec (recursively).
+ * - No spec (`undefined`): every scalar field, no relations.
+ */
+type Shape<T, Spec, Mode extends SpecMode> = Simplify<{
+    [K in keyof T as K extends ResultScalarKeys<T, Spec, Mode> ? K : never]: T[K];
+} & {
+    [K in keyof T as K extends ResultRelationKeys<T, Spec> ? K : never]: MapRelation<T[K], SubSpec<Spec, K>, Mode>;
+}>;
+/**
+ * Resolves the shape of a single entity `T` (not an array, not nullable) from the method options.
+ * `select` takes precedence: when present, `relations` is ignored. If the option that drives
+ * the shape is not narrowed, its contents are unknown and `T` is returned unchanged.
+ */
+type InferEntity<T, O> = OptionState<O, "select"> extends "known" ? Shape<T, NonNullable<Get<O, "select">>, "select"> : OptionState<O, "select"> extends "unknown" ? T : OptionState<O, "relations"> extends "known" ? Shape<T, NonNullable<Get<O, "relations">>, "relations"> : OptionState<O, "relations"> extends "unknown" ? T : Shape<T, undefined, "relations">;
+/**
+ * Opt-in **strict** return typing: narrows the type returned by a repository method
+ * according to the `select` / `relations` that were actually passed to it.
+ *
+ * By default, `VSRepository` methods type their return as the whole entity, ignoring
+ * `select` and `relations` (the same approach TypeORM takes). Use this utility when you
+ * prefer a tighter type:
+ *
+ * - **no `select`/`relations`** — only the scalar fields of the entity (no relations);
+ * - **`relations`** — the scalar fields plus the requested relations (nested ones included);
+ * - **`select`** — only the selected fields. A relation selected with `true` brings all of its
+ *   scalar fields; a nested `select` restricts it further. Relations selected this way are
+ *   loaded even without `relations`.
+ *
+ * `select` takes precedence over `relations`: when `select` is present, `relations` is
+ * ignored by the type. This mirrors the Prisma 7 adapter and never promises fields an
+ * adapter might not return.
+ *
+ * `see` and `db` don't affect the result type.
+ *
+ * The first type argument is what the method returns: `Entity`, `Entity | null` or
+ * `Entity[]` — `null`/array-ness are preserved (also on relation fields, e.g.
+ * `address: Address | null`).
+ *
+ * The options must keep their literal type, so declare them with `satisfies MethodOptions<T>`
+ * (or inline). If the options are typed as plain `MethodOptions<T>`, nothing is known
+ * at compile time and the whole entity `T` is returned unchanged (the default typing).
+ *
+ * @template T What the method returns: `Entity`, `Entity | null` or `Entity[]`.
+ * @template Options The options object passed to the method (`typeof options`).
+ *
+ * @example
+ * ```ts
+ * const options = {
+ *     select: { id: true, name: true, products: { id: true } },
+ * } satisfies MethodOptions<User>;
+ *
+ * const users: InferMethodReturn<User[], typeof options> = await userRepository.getAll(options);
+ * // { id: string; name: string; products: { id: string }[] }[]
+ * ```
+ *
+ * @publicApi
+ */
+export type InferMethodReturn<T, Options extends InferMethodReturnOptions = {}> = T extends readonly (infer U)[] ? InferEntity<U, Options>[] : T extends null | undefined ? T : InferEntity<T, Options>;
+export {};

package/dist/types/utils/infer-method-return.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=infer-method-return.type.js.map

package/dist/types/utils/infer-method-return.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer-method-return.type.js","sourceRoot":"","sources":["../../../src/types/utils/infer-method-return.type.ts"],"names":[],"mappings":""}

package/dist/types/utils/infer-method-type.type.d.ts

@@ -0,0 +1,66 @@
+import { VSRepoOrmTypes } from "../vsrepo/vsrepo-orm-types.type";
+import { VSRepoRelations } from "../vsrepo/vsrepo-relations.type";
+import { VSRepoSelect } from "../vsrepo/vsrepo-select.type";
+import { InferMethodReturn } from "./infer-method-return.type";
+import { MethodOptions } from "./methods-options.type";
+/** Entity type behind a method's return: `E`, `E | null`, `E[]` or `E[] | null` all give `E`. */
+type EntityOf<R> = NonNullable<R> extends readonly (infer U)[] ? U : NonNullable<R>;
+/**
+ * Deeply checks that a `select`/`relations` object only has keys that exist in the reference
+ * spec (`VSRepoSelect<E>`/`VSRepoRelations<E>`), turning unknown keys into `never`.
+ *
+ * Needed because a generic parameter (`Options` in {@link InferMethodType}) loses TypeScript's
+ * excess property check, so a typo like `select: { id: true, idd: true }` would otherwise be
+ * silently accepted.
+ *
+ * Non-object values (e.g. `true`) resolve to `unknown` (the identity of `&`): they are already
+ * validated by the `Options` constraint, and contributing nothing here keeps stray members of
+ * `boolean` (like `valueOf`) out of the editor's suggestions.
+ */
+type ExactSpec<S, Ref> = S extends object ? [Extract<Ref, object>] extends [never] ? never : {
+    [K in keyof S]: K extends keyof Extract<Ref, object> ? ExactSpec<S[K], NonNullable<Extract<Ref, object>[K]>> : never;
+} : unknown;
+/** Applies {@link ExactSpec} to `select` and `relations`; `see`/`db` pass through, unknown keys become `never`. */
+type ExactOptions<O, E> = {
+    [K in keyof O]: K extends "select" ? ExactSpec<O[K], VSRepoSelect<E>> : K extends "relations" ? ExactSpec<O[K], VSRepoRelations<E>> : K extends "see" | "db" ? O[K] : never;
+};
+/**
+ * Type for declaring a dynamic method whose return type is **strictly inferred** from the
+ * `select` / `relations` passed on each call (see {@link InferMethodReturn} for the exact rules).
+ *
+ * It has two call signatures:
+ * - `(...args) => Promise<...>` — no `options`: only the scalar fields of the entity;
+ * - `(...args, options?: MethodOptions<Entity, OrmTypes>) => Promise<...>` — the return is
+ *   inferred from the `options` passed.
+ *
+ * `Entity` is taken from the return type (`Entity`, `Entity | null`, `Entity[]`, ...).
+ *
+ * The `options` parameter is always the last one, after every argument in `Args` (as in a
+ * regular dynamic method signature). Unknown keys in `select`/`relations` are rejected, just like
+ * with a plain `MethodOptions<Entity>` parameter, and the editor autocompletes them.
+ *
+ * Meant for dynamic methods that return entities. Methods that don't (`existsBy...`,
+ * `countBy...`, etc.) can keep their regular signature.
+ *
+ * @template Args Positional arguments of the method, without `options` (e.g. `[name: string]`).
+ * @template R What the method resolves to: `Entity`, `Entity | null` or `Entity[]`.
+ * @template K ORM type map (`dbClient`/`dbTransaction`) used to type the `db` option. Optional.
+ *
+ * @example
+ * ```ts
+ * class UserRepository extends VSRepository<User, string, MyOrmTypes> {
+ *     @DynamicMethod()
+ *     declare findByName: InferMethodType<[name: string], User[], MyOrmTypes>;
+ * }
+ *
+ * const users = await userRepository.findByName("John", { select: { id: true, name: true } });
+ * // { id: string; name: string }[]
+ * ```
+ *
+ * @publicApi
+ */
+export type InferMethodType<Args extends unknown[], R, K extends VSRepoOrmTypes = VSRepoOrmTypes> = {
+    (...args: Args): Promise<InferMethodReturn<R, {}>>;
+    <Options extends MethodOptions<EntityOf<R>, K>>(...args: [...Args, options?: Options & ExactOptions<Options, EntityOf<R>>]): Promise<InferMethodReturn<R, Options>>;
+};
+export {};

package/dist/types/utils/infer-method-type.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=infer-method-type.type.js.map

package/dist/types/utils/infer-method-type.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer-method-type.type.js","sourceRoot":"","sources":["../../../src/types/utils/infer-method-type.type.ts"],"names":[],"mappings":""}

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

@@ -9,16 +9,12 @@ 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;
+    [P in keyof T as NonNullable<T[P]> extends Primitive ? P : never]?: SortDirection;
 };
 /**
  * Ordering accepted by repository methods that support `order`, such as `getAll` or a dynamic method with `Ordered`.

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

@@ -14,7 +14,7 @@ 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>;
+    pkName?: KeysOfType<T, K>;
     /**
      * Name of the field used for soft-delete.
      *

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "vsrepo",
-  "version": "2.4.0",
-  "description": "ORM-agnostic repository pattern library with full TypeScript support and automatic type inference.",
+  "version": "2.5.0",
+  "description": "ORM-agnostic repository pattern library",
   "homepage": "https://github.com/jaobrabo123/VSRepository#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jaobrabo123/VSRepository.git"
   },
+  "bugs": {
+    "email": "joaodev.azevedo@outlook.com",
+    "url": "https://github.com/jaobrabo123/VSRepoDrizzleAdapter/issues"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -20,7 +24,8 @@
   "files": [
     "dist",
     "README.md",
-    "README.pt-BR.md"
+    "README.pt-BR.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"
@@ -38,6 +43,7 @@
   "keywords": [
     "prisma",
     "typeorm",
+    "drizzle",
     "repository",
     "orm",
     "typescript",