@zudojs/database 1.0.0 → 1.1.0

package/README.md

@@ -191,7 +191,9 @@ import { assertDatabaseHealth, checkDatabaseHealth, createLockManager } from "@z
 const locks = createLockManager(client);
 
 // Advisory lock (FNV-1a 64 key, transaction-scoped). `timeoutMs` becomes
-// `SET LOCAL lock_timeout`; the transaction timeout is raised to cover it.
+// `SET LOCAL lock_timeout` (at least 1 ms; PostgreSQL treats 0 as "no
+// timeout", so 0 is rejected — use `noWait` to fail immediately); the
+// transaction timeout is raised to cover it.
 await locks.withAdvisoryLock("reports:nightly", async (tx) => {
   await tx.$executeRawUnsafe("REFRESH MATERIALIZED VIEW nightly_report");
 }, { timeoutMs: 10_000 });
@@ -233,7 +235,7 @@ await assertDatabaseHealth(client); // throws DatabaseUnhealthyError with the re
 - PostgreSQL only. Migration, seed, and lock helpers emit PostgreSQL SQL; other dialects throw `UnsupportedDialectError`.
 - No savepoints or nested transactions. Prisma interactive transactions are used as-is.
 - Connection pooling is handled by the driver adapter, not by this package.
-- `timeoutMs` and `signal` on repository operations are client-side only; the database query is not cancelled server-side.
+- `timeoutMs` and `signal` on repository operations are client-side only; the database query is not cancelled server-side. A `signal` passed to `transaction()` / `withTransaction()` does roll the transaction back: the abort is raised inside the Prisma callback.
 - The cache is not transaction-aware. Do not populate it from inside a transaction that may roll back.
 
 ## Use Cases

package/dist/databaseClient/databaseClient.core.d.ts

@@ -11,7 +11,7 @@
  * Only PostgreSQL is exercised by the runners, locks and health helpers in
  * this package.
  */
-import { type Prisma } from "@prisma/client";
+import type { Prisma } from "@prisma/client";
 import { DatabaseError } from "@zudojs/errors";
 import type { DatabaseClient as DatabaseClientContract, DatabaseConnectionOptions, DatabaseHealth, DatabaseLogger, DatabaseOperationOptions, DatabaseStatus, TransactionCallback, TransactionIsolationLevel, TransactionOptions } from "../databaseType/databaseType.type.js";
 /**
@@ -129,6 +129,12 @@ export declare class DatabaseClient implements DatabaseClientContract<DatabaseTr
     healthCheck(options?: RawQueryOptions): Promise<DatabaseHealth>;
     /**
      * Runs a callback inside a Prisma interactive transaction.
+     *
+     * When `options.signal` aborts, the abort is raised *inside* the
+     * transaction callback so Prisma rolls the transaction back; the caller
+     * is released at the same moment. Racing only the outer promise let the
+     * callback finish and the transaction commit after the caller had
+     * already been told it was aborted.
      */
     transaction<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
     /**

package/dist/databaseClient/databaseClient.core.js

@@ -11,7 +11,7 @@
  * Only PostgreSQL is exercised by the runners, locks and health helpers in
  * this package.
  */
-import { PrismaClient } from "@prisma/client";
+import { createRequire } from "node:module";
 import { DatabaseError, DatabaseOperation } from "@zudojs/errors";
 import { createDefaultLogger } from "./databaseClient.logger.js";
 import { normalizeDatabaseError } from "./databaseClient.errors.js";
@@ -174,6 +174,12 @@ export class DatabaseClient {
     }
     /**
      * Runs a callback inside a Prisma interactive transaction.
+     *
+     * When `options.signal` aborts, the abort is raised *inside* the
+     * transaction callback so Prisma rolls the transaction back; the caller
+     * is released at the same moment. Racing only the outer promise let the
+     * callback finish and the transaction commit after the caller had
+     * already been told it was aborted.
      */
     async transaction(callback, options = {}) {
         if (typeof callback !== "function") {
@@ -183,7 +189,7 @@ export class DatabaseClient {
         await this.ensureConnected();
         const transactionOptions = buildPrismaTransactionOptions(options);
         try {
-            return await raceAbort(this.prisma.$transaction(async (transaction) => callback(transaction), transactionOptions), options.signal);
+            return await raceAbort(this.prisma.$transaction(async (transaction) => raceAbort(callback(transaction), options.signal), transactionOptions), options.signal);
         }
         catch (error) {
             const normalized = normalizeDatabaseError(error, {
@@ -321,6 +327,46 @@ export class DatabaseClient {
         }
     }
 }
+const requirePeer = createRequire(import.meta.url);
+let cachedPrismaClientConstructor;
+/**
+ * Resolves the generated `PrismaClient` constructor on first use.
+ *
+ * The lookup is deliberately lazy. `@prisma/client` is a peer dependency, and
+ * until the consumer runs `prisma generate` the installed package is a stub
+ * that exports no `PrismaClient`. A static value import therefore made merely
+ * importing `@zudojs/database` fail with a bare `SyntaxError` — including for
+ * consumers who pass their own client through `options.prisma`, or whose
+ * generated client lives in a custom output directory (the Prisma 7 default)
+ * and so never needs this constructor at all.
+ *
+ * @throws {DatabaseError} when no generated client can be resolved.
+ */
+function resolvePrismaClientConstructor() {
+    if (cachedPrismaClientConstructor)
+        return cachedPrismaClientConstructor;
+    const guidance = "Install it and run `prisma generate`, or pass an already-constructed client as `prisma` in the DatabaseClient options.";
+    let module;
+    try {
+        module = requirePeer("@prisma/client");
+    }
+    catch {
+        throw new DatabaseError(`DatabaseClient could not load the "@prisma/client" peer dependency. ${guidance}`, {
+            code: "ERR_DATABASE_CONNECTION",
+            operation: DatabaseOperation.CONNECT,
+            isOperational: false,
+        });
+    }
+    if (typeof module.PrismaClient !== "function") {
+        throw new DatabaseError(`"@prisma/client" is installed but exports no PrismaClient, which means the client has not been generated yet. ${guidance}`, {
+            code: "ERR_DATABASE_CONNECTION",
+            operation: DatabaseOperation.CONNECT,
+            isOperational: false,
+        });
+    }
+    cachedPrismaClientConstructor = module.PrismaClient;
+    return cachedPrismaClientConstructor;
+}
 /**
  * Builds a Prisma client from the supplied options.
  *
@@ -342,7 +388,7 @@ function createPrismaClient(options) {
         ]
         : [{ emit: "stdout", level: "error" }];
     try {
-        const Constructor = PrismaClient;
+        const Constructor = resolvePrismaClientConstructor();
         return new Constructor({ adapter: options.adapter, log });
     }
     catch (error) {

package/dist/locks/locks.core.d.ts

@@ -22,6 +22,10 @@ export interface DatabaseLockOptions {
      * transaction timeout. When it exceeds Prisma's 5 s default and
      * `transaction.timeoutMs` is not set, the transaction timeout is raised
      * automatically (see `resolveLockTransactionOptions`).
+     *
+     * Must be a positive number: PostgreSQL treats `lock_timeout = 0` as
+     * "disabled" (wait forever), so `0` is rejected. Use `noWait` to fail
+     * immediately instead.
      */
     readonly timeoutMs?: number;
     /**

package/dist/locks/locks.core.js

@@ -203,9 +203,7 @@ export function resolveLockTransactionOptions(options = {}) {
     const { timeoutMs, transaction } = options;
     if (timeoutMs === undefined)
         return transaction;
-    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
-        throw new TypeError("Lock timeoutMs must be a non-negative finite number.");
-    }
+    validateLockTimeout(timeoutMs);
     const explicit = transaction?.timeoutMs;
     if (explicit !== undefined) {
         if (explicit <= timeoutMs) {
@@ -226,11 +224,19 @@ export function resolveLockTransactionOptions(options = {}) {
 async function applyLockTimeout(transaction, timeoutMs) {
     if (timeoutMs === undefined)
         return;
-    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
-        throw new TypeError("Lock timeoutMs must be a non-negative finite number.");
-    }
+    validateLockTimeout(timeoutMs);
     await transaction.$executeRawUnsafe(`SET LOCAL lock_timeout = ${Math.floor(timeoutMs)}`);
 }
+/**
+ * Rejects lock timeouts PostgreSQL would silently disable. `lock_timeout`
+ * is "no timeout" at `0`, and `Math.floor` turns any value below 1 ms into
+ * `0`, so anything under one millisecond is refused.
+ */
+function validateLockTimeout(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+        throw new TypeError("Lock timeoutMs must be a finite number of at least 1 ms; PostgreSQL treats lock_timeout = 0 as disabled. Use noWait to fail immediately.");
+    }
+}
 function validateCallback(callback) {
     if (typeof callback !== "function") {
         throw new TypeError("A lock callback is required.");

package/dist/repository/repository.base.d.ts

@@ -254,12 +254,25 @@ export declare abstract class BaseRepository<TEntity, TId = string, TCreateInput
      * Builds the primary-key `where` for an identifier.
      */
     protected whereId(id: TId): Record<string, unknown>;
+    /**
+     * Builds the primary-key `where` for a *unique* operation (`update`),
+     * folding the soft-delete scope in as a sibling of the id rather than
+     * wrapping it in `AND`. Prisma's `WhereUniqueInput` requires the unique
+     * field at the top level, so `{ AND: [{ id }, { deletedAt: null }] }` is
+     * rejected with a validation error.
+     */
+    protected whereUniqueId(id: TId): Record<string, unknown>;
     /**
      * Applies the soft-delete scope to a filter when enabled.
      */
     protected scope(filter?: TWhereInput): TWhereInput | undefined;
     /**
      * Converts generic sort definitions into Prisma-compatible orderBy.
+     *
+     * Field names and directions are validated the same way the query
+     * builder validates them (`toPrismaOrderBy`), so a sort taken from
+     * request input cannot reach the delegate with an arbitrary key or an
+     * unsupported direction.
      */
     protected buildOrderBy<TField extends string>(sort?: readonly SortInput<TField>[]): ReadonlyArray<Record<string, string>> | undefined;
     private isScoped;

package/dist/repository/repository.base.js

@@ -1,7 +1,7 @@
 import { DatabaseError } from "@zudojs/errors";
 import { createPaginationMeta, normalizeLimit, normalizePage, } from "../pagination/pagination.core.js";
 import { buildKeysetWhere, createKeysetPage, decodeKeysetCursor, } from "../pagination/pagination.keyset.js";
-import { toPrismaArgs } from "../queryBuilder/queryBuilder.prisma.js";
+import { toPrismaArgs, toPrismaOrderBy, } from "../queryBuilder/queryBuilder.prisma.js";
 import { createAbortError, createTimeoutError, mapRepositoryError, } from "./repository.errors.js";
 const DEFAULT_SOFT_DELETE_FIELD = "deletedAt";
 const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -121,12 +121,15 @@ export class BaseRepository {
         const page = normalizePage(options?.pagination?.page);
         const limit = normalizeLimit(options?.pagination?.limit);
         const skip = (page - 1) * limit;
+        // Validated before either query is dispatched, so an invalid sort never
+        // costs a `count` round-trip.
+        const orderBy = this.buildOrderBy(options?.sort);
         const [data, total] = await Promise.all([
             this.execute("findPaginated", () => this.delegate.findMany({
                 where: this.scope(filter),
                 skip,
                 take: limit,
-                orderBy: this.buildOrderBy(options?.sort),
+                orderBy,
             }), options),
             this.count(filter, options),
         ]);
@@ -154,6 +157,7 @@ export class BaseRepository {
             this.validateFilter(filter);
         }
         const sort = this.buildCursorSort(options?.sort);
+        const orderBy = this.buildOrderBy(sort);
         const limit = normalizeLimit(options?.limit);
         const cursor = options?.cursor ?? null;
         let where = this.scope(filter);
@@ -165,7 +169,7 @@ export class BaseRepository {
         const rows = await this.execute("paginateCursor", () => this.delegate.findMany({
             where: where,
             take: limit + 1,
-            orderBy: this.buildOrderBy(sort),
+            orderBy,
         }), options);
         return createKeysetPage(rows, {
             sort,
@@ -251,7 +255,7 @@ export class BaseRepository {
             throw new DatabaseError(`Cannot update ${this.modelName}: input is required.`);
         }
         return this.execute("update", () => this.delegate.update({
-            where: this.scope(this.whereId(id)),
+            where: this.whereUniqueId(id),
             data: input,
         }), options);
     }
@@ -445,6 +449,17 @@ export class BaseRepository {
     whereId(id) {
         return { [this.idField]: id };
     }
+    /**
+     * Builds the primary-key `where` for a *unique* operation (`update`),
+     * folding the soft-delete scope in as a sibling of the id rather than
+     * wrapping it in `AND`. Prisma's `WhereUniqueInput` requires the unique
+     * field at the top level, so `{ AND: [{ id }, { deletedAt: null }] }` is
+     * rejected with a validation error.
+     */
+    whereUniqueId(id) {
+        const where = this.whereId(id);
+        return this.isScoped() ? { ...where, [this.softDeleteField]: null } : where;
+    }
     /**
      * Applies the soft-delete scope to a filter when enabled.
      */
@@ -460,14 +475,14 @@ export class BaseRepository {
     }
     /**
      * Converts generic sort definitions into Prisma-compatible orderBy.
+     *
+     * Field names and directions are validated the same way the query
+     * builder validates them (`toPrismaOrderBy`), so a sort taken from
+     * request input cannot reach the delegate with an arbitrary key or an
+     * unsupported direction.
      */
     buildOrderBy(sort) {
-        if (!sort || sort.length === 0) {
-            return undefined;
-        }
-        return sort.map((entry) => ({
-            [entry.field]: entry.direction,
-        }));
+        return toPrismaOrderBy(sort);
     }
     isScoped() {
         return this.softDeleteField !== undefined && !this.includeDeleted;

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/database",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Database abstraction layer with clients, repositories, transactions, and query building for Zudojs applications.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +41,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/errors": "1.0.1"
   },
   "peerDependencies": {
     "@prisma/client": ">=7.0.0 <8"