vsrepo 1.4.2 → 2.1.0

package/dist/VSRepoAdapter.d.ts

@@ -0,0 +1,109 @@
+import { AdapterMethodOptions } from "./types/adapter/adapter-method-options.type";
+import { AdapterQueryOptions } from "./types/adapter/adapter-query-options.type";
+import { CountResult } from "./types/utils/count-result.type";
+import { DeepPartial } from "./types/utils/deep-partial.type";
+import { NumericKeys } from "./types/utils/numeric-keys.type";
+import { VSRepoTransactionOptions } from "./types/vsrepo/vsrepo-transaction-options.type";
+import { VSRepoWhere } from "./types/vsrepo/vsrepo-where.type";
+/**
+ * Contract implemented by ORM-specific adapters (e.g. Prisma, TypeORM) that
+ * `VSRepository` delegates every operation to.
+ *
+ * Implementing this class is what makes `VSRepository` usable with a given
+ * ORM/database: `VSRepository` never talks to the ORM directly, it only
+ * calls these methods with already-resolved `VSRepoWhere`/`AdapterMethodOptions`.
+ *
+ * @template T Entity type this adapter operates on.
+ *
+ * @publicApi
+ */
+export declare abstract class VSRepoAdapter<T> {
+    /** Runs `fn` inside a native transaction of the underlying ORM/database. */
+    abstract runInTransaction<R>(fn: (tx: any) => Promise<R>, options?: VSRepoTransactionOptions): Promise<R>;
+    /** Returns the underlying ORM client instance used outside of transactions. */
+    abstract getDbClient(): any;
+    /** Executes a raw query/statement against the underlying database, used by `@QueryMethod`. */
+    abstract query<T = any>(query: string, options?: AdapterQueryOptions): Promise<T>;
+    /** Fetches a single record matching `where`. */
+    abstract findOne(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T | null>;
+    /** Fetches a single record matching `where`, throwing if none is found. */
+    abstract findOneOrThrow(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Fetches all records matching `where`. */
+    abstract findMany(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T> & {
+        distinct?: (keyof T)[];
+    }): Promise<T[]>;
+    /** Creates or updates (upsert) a single record. */
+    abstract save(obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Creates or updates (upsert) multiple records in a single operation. */
+    abstract saveMany(objs: DeepPartial<T>[], options?: AdapterMethodOptions<T>): Promise<T[]>;
+    /** Creates a single record. */
+    abstract create(objs: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Creates multiple records in a single operation. */
+    abstract createMany(objs: DeepPartial<T>[], options?: AdapterMethodOptions<T> & {
+        ignoreConflicts?: boolean;
+    }): Promise<CountResult>;
+    /** Creates multiple records in a single operation, returning the created records. */
+    abstract createManyReturning(objs: DeepPartial<T>[], options?: AdapterMethodOptions<T> & {
+        ignoreConflicts?: boolean;
+    }): Promise<T[]>;
+    /** Deletes a single record matching `where`. */
+    abstract delete(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Deletes every record matching `where`, returning the count of affected rows. */
+    abstract deleteMany(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<CountResult>;
+    /** Deletes every record matching `where`, returning the deleted records. */
+    abstract deleteManyReturning(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T[]>;
+    /** Updates a single record matching `where`. */
+    abstract update(where: VSRepoWhere<T>, obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Updates every record matching `where`, returning the count of affected rows. */
+    abstract updateMany(where: VSRepoWhere<T>, obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<CountResult>;
+    /** Updates every record matching `where`, returning the updated records. */
+    abstract updateManyReturning(where: VSRepoWhere<T>, obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T[]>;
+    /** Returns the number of records matching `where`. */
+    abstract count(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number>;
+    /** Checks whether at least one record matching `where` exists. */
+    abstract exists(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<boolean>;
+    /**
+     * Fetches a single record matching `where` and returns it deep-merged, in
+     * memory, with the provided object — does **not** persist anything.
+     */
+    abstract merge<K>(where: VSRepoWhere<T>, obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<K & T>;
+    /** Creates a record if none matches `where`, otherwise updates it. */
+    abstract upsert(where: VSRepoWhere<T>, create: DeepPartial<T>, update: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Atomically adds `value` to `field` on the single record matching
+     * `where` — equivalent to `UPDATE ... SET field = field + value WHERE
+     * ...`, evaluated server-side against the row's current value (not a
+     * client-side read-modify-write).
+     *
+     * Implementations must return the record reflecting the state *after*
+     * the write. If the underlying ORM's atomic-update API doesn't already
+     * return the updated row (e.g. it only returns an affected-row count),
+     * issue a follow-up read instead of returning a stale in-memory copy.
+     */
+    abstract incrementOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Same as {@link VSRepoAdapter.incrementOne}, subtracting `value` instead of adding it. */
+    abstract decrementOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Same as {@link VSRepoAdapter.incrementOne}, multiplying the field's current value by `value`. */
+    abstract multiplyOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Same as {@link VSRepoAdapter.incrementOne}, dividing the field's
+     * current value by `value`. Division-by-zero behavior is not
+     * standardized by this contract — it is whatever the underlying
+     * database/driver does natively (e.g. Postgres raises a
+     * `division_by_zero` error); document your adapter's actual behavior.
+     */
+    abstract divideOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Returns the sum of `field` across every record matching `where` (all
+     * records if `where` is omitted/empty), or `null` if no record
+     * matches — mirroring SQL's `SUM()`, which returns `NULL` (not `0`)
+     * over an empty set.
+     */
+    abstract sum(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoAdapter.sum}, but the arithmetic mean (`AVG()`) instead of the total. */
+    abstract average(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoAdapter.sum}, but the minimum value (`MIN()`) instead of the total. */
+    abstract min(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoAdapter.sum}, but the maximum value (`MAX()`) instead of the total. */
+    abstract max(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+}

package/dist/VSRepoAdapter.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VSRepoAdapter = void 0;
+/**
+ * Contract implemented by ORM-specific adapters (e.g. Prisma, TypeORM) that
+ * `VSRepository` delegates every operation to.
+ *
+ * Implementing this class is what makes `VSRepository` usable with a given
+ * ORM/database: `VSRepository` never talks to the ORM directly, it only
+ * calls these methods with already-resolved `VSRepoWhere`/`AdapterMethodOptions`.
+ *
+ * @template T Entity type this adapter operates on.
+ *
+ * @publicApi
+ */
+class VSRepoAdapter {
+}
+exports.VSRepoAdapter = VSRepoAdapter;