@zudojs/database 1.2.1 → 1.3.0

package/README.md

@@ -116,8 +116,22 @@ const next = await users.paginateCursor(undefined, {
   limit: 25,
   sort: [{ field: "createdAt", direction: "desc" }],
 });
+// Page back: `previousCursor` is set on any non-empty page requested with a
+// cursor. The rows come back in the requested sort order.
+const back = await users.paginateCursor(undefined, {
+  cursor: next.meta.previousCursor,
+  limit: 25,
+  sort: [{ field: "createdAt", direction: "desc" }],
+});
 ```
 
+A missing, forged, tampered or malformed cursor rejects with a
+`ValidationError` (400, exposable, `issues[0].code` such as
+`"cursor_signature"`) before any query runs. The message never echoes the
+cursor or its contents. Building keyset pages by hand? Fetch with
+`keysetFetchSort(sort, getKeysetDirection(payload))` and pass that
+`direction` to `createKeysetPage`.
+
 ## Migrations and seeds
 
 ```typescript
@@ -163,7 +177,14 @@ to size it for long-running steps.
 
 ## Errors
 
-Every failure surfaces as a `DatabaseError` from `@zudojs/errors`. Prisma codes
+Errors your own transaction callback throws that are already `@zudojs/errors`
+errors but not database errors (a `NotFoundError`, `DomainError`,
+`ValidationError`, ...) roll the transaction back and propagate **unchanged**
+from `transaction()`, `withTransaction()`, `TransactionManager` and units of
+work: same instance, same status, and not logged as a database error.
+Everything else, driver and database failures included, is normalised as below.
+
+Every database failure surfaces as a `DatabaseError` from `@zudojs/errors`. Prisma codes
 are mapped to `databaseCode`, an `ErrorCode` and an HTTP status (`P2002` /
 `P2003` → 409, `P2025` → 404, `P2034` → retryable, `P1xxx` → 503 with a fixed
 message that never includes the host name).
@@ -209,6 +230,10 @@ await locks.withRowLock("orders", orderId, async (tx) => {
   await tx.$executeRawUnsafe('UPDATE "orders" SET "status" = $1 WHERE "id" = $2', "paid", orderId);
 }, { mode: "for-no-key-update", skipLocked: true });
 
+// The connection manager reconnects with exponential back-off after failed
+// health checks. The back-off wait keeps the process alive until the reconnect
+// finishes; `disconnect()` / `destroy()` cancel it immediately.
+
 const health = await checkDatabaseHealth(client, { timeoutMs: 2_000 });
 health.status; // "healthy" | "degraded" | "unhealthy"
 await assertDatabaseHealth(client); // throws DatabaseUnhealthyError with the real cause

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

@@ -41,7 +41,16 @@ export interface PrismaTransactionOptions {
 export interface PrismaClientLike {
     $connect(): Promise<void>;
     $disconnect(): Promise<void>;
-    $transaction<TResult>(callback: (transaction: DatabaseTransactionContext) => Promise<TResult>, options?: PrismaTransactionOptions): Promise<TResult>;
+    /**
+     * Declared loosely on purpose. Prisma 7 generates the client into the
+     * application (`prisma-client` generator), and its overloaded
+     * `$transaction` (batch array or interactive callback) cannot be assigned
+     * to a single generic signature, so a real client failed to type-check
+     * against this interface and needed a cast. Any `$transaction` is
+     * accepted here; `DatabaseClient` only ever calls the interactive form
+     * (see `InteractiveTransaction`).
+     */
+    $transaction(...args: never[]): Promise<unknown>;
     $queryRawUnsafe<TResult = unknown>(query: string, ...values: unknown[]): Promise<TResult>;
     $executeRawUnsafe(query: string, ...values: unknown[]): Promise<number>;
     $on?(event: "query", callback: (event: PrismaQueryEvent) => void): void;
@@ -135,6 +144,12 @@ export declare class DatabaseClient implements DatabaseClientContract<DatabaseTr
      * 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.
+     *
+     * A `@zudojs/errors` `BaseError` thrown by the callback that is not a
+     * `DatabaseError` (a `NotFoundError`, `DomainError`, `ValidationError`,
+     * ...) rolls the transaction back and is rethrown unchanged, without
+     * being logged as a database failure. Driver and database failures, and
+     * any other thrown value, are normalised to a `DatabaseError` and logged.
      */
     transaction<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
     /**

package/dist/databaseClient/databaseClient.core.js

@@ -14,7 +14,7 @@
 import { createRequire } from "node:module";
 import { DatabaseError, DatabaseOperation } from "@zudojs/errors";
 import { createDefaultLogger } from "./databaseClient.logger.js";
-import { normalizeDatabaseError } from "./databaseClient.errors.js";
+import { isNonDatabaseBaseError, normalizeDatabaseError, } from "./databaseClient.errors.js";
 /**
  * Isolation levels accepted by Prisma's interactive transactions. The
  * values are identical to the string names, so no namespace lookup is
@@ -180,6 +180,12 @@ export class DatabaseClient {
      * 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.
+     *
+     * A `@zudojs/errors` `BaseError` thrown by the callback that is not a
+     * `DatabaseError` (a `NotFoundError`, `DomainError`, `ValidationError`,
+     * ...) rolls the transaction back and is rethrown unchanged, without
+     * being logged as a database failure. Driver and database failures, and
+     * any other thrown value, are normalised to a `DatabaseError` and logged.
      */
     async transaction(callback, options = {}) {
         if (typeof callback !== "function") {
@@ -188,10 +194,17 @@ export class DatabaseClient {
         throwIfAborted(options.signal);
         await this.ensureConnected();
         const transactionOptions = buildPrismaTransactionOptions(options);
+        const interactive = this.prisma.$transaction.bind(this.prisma);
         try {
-            return await raceAbort(this.prisma.$transaction(async (transaction) => raceAbort(callback(transaction), options.signal), transactionOptions), options.signal);
+            return await raceAbort(interactive(async (transaction) => raceAbort(callback(transaction), options.signal), transactionOptions), options.signal);
         }
         catch (error) {
+            if (isNonDatabaseBaseError(error)) {
+                this.logger.debug("Database transaction rolled back by caller error.", {
+                    code: error.code,
+                });
+                throw error;
+            }
             const normalized = normalizeDatabaseError(error, {
                 operation: DatabaseOperation.TRANSACTION,
                 fallbackMessage: "Database transaction failed.",

package/dist/databaseClient/databaseClient.errors.d.ts

@@ -11,7 +11,7 @@
  * `clientVersion`), so the mapping works regardless of which copy of
  * `@prisma/client` produced the error.
  */
-import { DatabaseError, DatabaseOperation, type DatabaseErrorOptions } from "@zudojs/errors";
+import { DatabaseError, DatabaseOperation, type BaseError, type DatabaseErrorOptions } from "@zudojs/errors";
 import type { DatabaseErrorInfo } from "../databaseType/databaseType.type.js";
 /**
  * Structural `DatabaseError` guard.
@@ -23,6 +23,17 @@ import type { DatabaseErrorInfo } from "../databaseType/databaseType.type.js";
  * (`category: "database"` plus a string `code`).
  */
 export declare function isDatabaseErrorLike(value: unknown): value is DatabaseError;
+/**
+ * Determines whether an error is a `@zudojs/errors` `BaseError` that is
+ * *not* a database failure: a domain, application, validation, not-found
+ * or other error raised by caller code.
+ *
+ * Transaction helpers (`DatabaseClient.transaction`, `withTransaction`,
+ * `TransactionManager`, units of work) roll back on such an error and
+ * rethrow the same instance unchanged, instead of wrapping it in a 500
+ * `DatabaseError` and logging it as a database failure.
+ */
+export declare function isNonDatabaseBaseError(value: unknown): value is BaseError;
 /**
  * Semantic outcome of a database failure.
  */

package/dist/databaseClient/databaseClient.errors.js

@@ -11,7 +11,7 @@
  * `clientVersion`), so the mapping works regardless of which copy of
  * `@prisma/client` produced the error.
  */
-import { DatabaseError, DatabaseOperation, ErrorCategory, isDatabaseError, ErrorCode, } from "@zudojs/errors";
+import { DatabaseError, DatabaseOperation, ErrorCategory, isBaseError, isDatabaseError, ErrorCode, } from "@zudojs/errors";
 /**
  * Structural `DatabaseError` guard.
  *
@@ -31,6 +31,19 @@ export function isDatabaseErrorLike(value) {
         typeof candidate.code === "string" &&
         typeof candidate.statusCode === "number");
 }
+/**
+ * Determines whether an error is a `@zudojs/errors` `BaseError` that is
+ * *not* a database failure: a domain, application, validation, not-found
+ * or other error raised by caller code.
+ *
+ * Transaction helpers (`DatabaseClient.transaction`, `withTransaction`,
+ * `TransactionManager`, units of work) roll back on such an error and
+ * rethrow the same instance unchanged, instead of wrapping it in a 500
+ * `DatabaseError` and logging it as a database failure.
+ */
+export function isNonDatabaseBaseError(value) {
+    return isBaseError(value) && !isDatabaseErrorLike(value);
+}
 const CONNECTION_MESSAGE = "Database connection failed.";
 const PRISMA_CODE_MAP = Object.freeze({
     // Query engine errors

package/dist/databaseClient/index.d.ts

@@ -4,5 +4,5 @@
  * Prisma-backed database client and connection infrastructure.
  */
 export { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike, type PrismaDriverAdapterLike, type PrismaQueryEvent, type PrismaTransactionOptions, type RawQueryOptions, } from "./databaseClient.core.js";
-export { normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, type DatabaseErrorKind, type NormalizeDatabaseErrorOptions, type PrismaErrorLike, } from "./databaseClient.errors.js";
+export { normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, type DatabaseErrorKind, type NormalizeDatabaseErrorOptions, type PrismaErrorLike, } from "./databaseClient.errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/databaseClient/index.js

@@ -4,5 +4,5 @@
  * Prisma-backed database client and connection infrastructure.
  */
 export { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, } from "./databaseClient.core.js";
-export { normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, } from "./databaseClient.errors.js";
+export { normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, } from "./databaseClient.errors.js";
 //# sourceMappingURL=index.js.map

package/dist/databaseConnection/databaseConnection.manager.d.ts

@@ -33,7 +33,9 @@ export interface DatabaseReconnectOptions {
     readonly maxAttempts?: number;
     /**
      * Base delay between reconnect attempts; doubles each attempt up to
-     * `maxDelayMs`. Defaults to 500 ms.
+     * `maxDelayMs`. Defaults to 500 ms. The wait keeps the process alive
+     * (a reconnect is never abandoned because the event loop drained) and
+     * is cancelled by `disconnect()` / `destroy()`.
      */
     readonly baseDelayMs?: number;
     /**
@@ -84,6 +86,7 @@ export declare class DatabaseConnectionManager {
     private healthCheckInFlight?;
     private consecutiveFailures;
     private reconnectPromise?;
+    private reconnectAbort?;
     private lastHealth?;
     private destroyed;
     constructor(options?: DatabaseConnectionManagerOptions);
@@ -97,7 +100,8 @@ export declare class DatabaseConnectionManager {
      */
     connect(): Promise<void>;
     /**
-     * Closes the database connection.
+     * Closes the database connection. Cancels an in-progress reconnect,
+     * including its backoff wait, so no further attempt is made.
      */
     disconnect(): Promise<void>;
     /**
@@ -153,6 +157,7 @@ export declare class DatabaseConnectionManager {
     destroy(): Promise<void>;
     private performScheduledHealthCheck;
     private reconnectWithBackoff;
+    private cancelReconnect;
     private performReconnect;
     private emit;
 }

package/dist/databaseConnection/databaseConnection.manager.js

@@ -20,6 +20,7 @@ export class DatabaseConnectionManager {
     healthCheckInFlight;
     consecutiveFailures = 0;
     reconnectPromise;
+    reconnectAbort;
     lastHealth;
     destroyed = false;
     constructor(options = {}) {
@@ -78,10 +79,12 @@ export class DatabaseConnectionManager {
         }
     }
     /**
-     * Closes the database connection.
+     * Closes the database connection. Cancels an in-progress reconnect,
+     * including its backoff wait, so no further attempt is made.
      */
     async disconnect() {
         this.stopHealthChecks();
+        this.cancelReconnect();
         const status = this.client.getStatus();
         if (status === "disconnected" || status === "disconnecting")
             return;
@@ -219,33 +222,47 @@ export class DatabaseConnectionManager {
     reconnectWithBackoff() {
         if (this.reconnectPromise)
             return this.reconnectPromise;
-        this.reconnectPromise = this.performReconnect().finally(() => {
+        const abort = new AbortController();
+        this.reconnectAbort = abort;
+        this.reconnectPromise = this.performReconnect(abort.signal).finally(() => {
             this.reconnectPromise = undefined;
+            if (this.reconnectAbort === abort)
+                this.reconnectAbort = undefined;
         });
         return this.reconnectPromise;
     }
-    async performReconnect() {
+    cancelReconnect() {
+        this.reconnectAbort?.abort();
+        this.reconnectAbort = undefined;
+    }
+    async performReconnect(signal) {
         const policy = this.reconnect;
         if (!policy)
             return;
         for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
-            if (this.destroyed)
+            if (this.destroyed || signal.aborted)
                 return;
             this.emit("reconnecting", undefined, attempt);
             try {
                 await this.client.disconnect().catch(() => undefined);
+                if (signal.aborted)
+                    return;
                 await this.client.connect();
+                if (signal.aborted)
+                    return;
                 this.consecutiveFailures = 0;
                 this.emit("connected", undefined, attempt);
                 return;
             }
             catch (error) {
+                if (signal.aborted)
+                    return;
                 this.emit("error", error, attempt);
                 if (attempt === policy.maxAttempts)
                     return;
                 const delay = Math.min(policy.maxDelayMs, policy.baseDelayMs * Math.pow(2, attempt - 1));
                 if (delay > 0)
-                    await sleep(delay);
+                    await sleep(delay, signal);
             }
         }
     }
@@ -266,10 +283,27 @@ export class DatabaseConnectionManager {
         }
     }
 }
-function sleep(milliseconds) {
+/**
+ * Backoff wait between reconnect attempts. The timer is deliberately *not*
+ * unref'd: a script whose only pending work is a reconnect must stay alive
+ * until the reconnect finishes. Aborting `signal` (from `disconnect()` or
+ * `destroy()`) clears the timer and resolves at once.
+ */
+function sleep(milliseconds, signal) {
     return new Promise((resolve) => {
-        const timer = setTimeout(resolve, milliseconds);
-        timer.unref?.();
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        signal.addEventListener("abort", onAbort, { once: true });
     });
 }
 /**

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  */
 export type { DatabaseOperationOptions, DatabaseStatus, TransactionIsolationLevel, DatabaseOperation, DatabaseConnectionOptions, DatabaseClientHealth, DatabaseHealth as DatabaseHealthInfo, TransactionOptions, TransactionCallback, Repository, SoftDeletableRepository, PaginationInput, PaginationMeta, PaginatedResult, SortDirection, SortInput, QueryOptions, DatabaseEntity, SoftDeletableEntity, AuditableEntity, DatabaseErrorInfo, DatabaseLogger, } from "./databaseType/index.js";
 export { noopDatabaseLogger } from "./databaseType/index.js";
-export { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike, type PrismaDriverAdapterLike, type PrismaQueryEvent, type PrismaTransactionOptions, type RawQueryOptions, type DatabaseErrorKind, type NormalizeDatabaseErrorOptions, type PrismaErrorLike, } from "./databaseClient/index.js";
+export { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike, type PrismaDriverAdapterLike, type PrismaQueryEvent, type PrismaTransactionOptions, type RawQueryOptions, type DatabaseErrorKind, type NormalizeDatabaseErrorOptions, type PrismaErrorLike, } from "./databaseClient/index.js";
 export { DatabaseConnectionManager, createConnectionManager, type DatabaseConnectionEvent, type DatabaseConnectionListener, type DatabaseConnectionEventDetails, type DatabaseConnectionManagerOptions, type DatabaseReconnectOptions, } from "./databaseConnection/index.js";
 export { Database, createDatabase, getDatabase, connectDatabase, disconnectDatabase, resetDatabase, } from "./database/index.js";
 export { BaseRepository, mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, type RepositoryDelegate, type BaseRepositoryOptions, type SoftDeleteOptions, type CursorQueryOptions, type TransactionClientLike, type RepositoryOperation, type RepositoryErrorContext, } from "./repository/index.js";
@@ -26,7 +26,7 @@ export { TransactionManager, createTransactionManager, withTransaction, withTran
 export { DatabaseUnitOfWork, createUnitOfWork, executeUnitOfWork, type UnitOfWork, type UnitOfWorkOptions, } from "./unitOfWork/index.js";
 export { QueryBuilder, createQueryBuilder, toPrismaWhere, toPrismaArgs, toPrismaOrderBy, toPrismaSelect, toPrismaSkipTake, type QueryCondition, type QueryFilter, type QueryOperator, type RelationOperator, type QueryBuilderState, type PrismaWhere, type PrismaQueryArgs, type ToPrismaArgsOptions, } from "./queryBuilder/index.js";
 export { equals, notEquals, inList, notInList, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, contains, startsWith, endsWith, isNull, isNotNull, and, or, not, condition, allOf, anyOf, fromObject, dateRange, oneOf, noneOf, optionalEquals, optionalContains, hasConditions, flattenAnd, cloneFilter, between, matchesPattern, isEmpty, isNotEmpty, dateOnly, isBefore, isAfter, isBetween, notCondition, relational, } from "./queryBuilder/index.js";
-export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, type CursorPayload, type EncodeCursorOptions, type DecodeCursorOptions, type KeysetPageOptions, type KeysetWhere, } from "./pagination/index.js";
+export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, createInvalidCursorError, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, type CursorPayload, type EncodeCursorOptions, type DecodeCursorOptions, type KeysetPageOptions, type KeysetWhere, type KeysetDirection, type InvalidCursorReason, } from "./pagination/index.js";
 export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, type RelationDefinition, type RelationType, type RelationLoadOptions, type RelationInclude, type ToPrismaIncludeOptions, } from "./relations/index.js";
 export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, normalizeAdvisoryKeyPair, resolveLockTransactionOptions, type DatabaseLockMode, type DatabaseLockOptions, type DatabaseLockResult, } from "./locks/index.js";
 export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, escapeCachePart, serializeCachePart, getOrSet, invalidateByPrefix, CACHE_KEY_SEPARATOR, type CacheEntry, type CacheOptions, type MemoryCacheOptions, type CacheStats, type DatabaseCache, } from "./cache/index.js";

package/dist/index.js

@@ -18,7 +18,7 @@
  */
 export { noopDatabaseLogger } from "./databaseType/index.js";
 // Client
-export { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, } from "./databaseClient/index.js";
+export { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, } from "./databaseClient/index.js";
 // Connection
 export { DatabaseConnectionManager, createConnectionManager, } from "./databaseConnection/index.js";
 // Database facade
@@ -33,7 +33,7 @@ export { DatabaseUnitOfWork, createUnitOfWork, executeUnitOfWork, } from "./unit
 export { QueryBuilder, createQueryBuilder, toPrismaWhere, toPrismaArgs, toPrismaOrderBy, toPrismaSelect, toPrismaSkipTake, } from "./queryBuilder/index.js";
 export { equals, notEquals, inList, notInList, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, contains, startsWith, endsWith, isNull, isNotNull, and, or, not, condition, allOf, anyOf, fromObject, dateRange, oneOf, noneOf, optionalEquals, optionalContains, hasConditions, flattenAnd, cloneFilter, between, matchesPattern, isEmpty, isNotEmpty, dateOnly, isBefore, isAfter, isBetween, notCondition, relational, } from "./queryBuilder/index.js";
 // Pagination
-export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination/index.js";
+export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, createInvalidCursorError, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination/index.js";
 // Relations
 export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, } from "./relations/index.js";
 // Locks

package/dist/pagination/index.d.ts

@@ -5,4 +5,6 @@
  */
 export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, type CursorPayload, type EncodeCursorOptions, type DecodeCursorOptions, } from "./pagination.core.js";
 export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, type KeysetPageOptions, type KeysetWhere, } from "./pagination.keyset.js";
+export { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, type KeysetDirection, } from "./pagination.keysetDirection.js";
+export { createInvalidCursorError, type InvalidCursorReason, } from "./pagination.cursorError.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/pagination/index.js

@@ -5,4 +5,6 @@
  */
 export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination.core.js";
 export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, } from "./pagination.keyset.js";
+export { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, } from "./pagination.keysetDirection.js";
+export { createInvalidCursorError, } from "./pagination.cursorError.js";
 //# sourceMappingURL=index.js.map

package/dist/pagination/pagination.core.d.ts

@@ -153,6 +153,10 @@ export declare function encodeCursor(value: unknown, options?: EncodeCursorOptio
  * When `secret` is supplied the signature is verified; when
  * `allowedFields` is supplied the payload must be a flat object whose keys
  * are all allowed and whose values are primitives.
+ *
+ * A missing, forged, tampered or malformed cursor throws a
+ * `ValidationError` (HTTP 400) whose message never echoes the cursor. An
+ * invalid `secret` is a programming error and still throws `TypeError`.
  */
 export declare function decodeCursor<T = unknown>(cursor: string, options?: DecodeCursorOptions): T;
 /**

package/dist/pagination/pagination.core.js

@@ -1,4 +1,5 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
+import { createInvalidCursorError } from "./pagination.cursorError.js";
 /**
  * Default pagination values.
  */
@@ -213,24 +214,28 @@ export function encodeCursor(value, options = {}) {
  * When `secret` is supplied the signature is verified; when
  * `allowedFields` is supplied the payload must be a flat object whose keys
  * are all allowed and whose values are primitives.
+ *
+ * A missing, forged, tampered or malformed cursor throws a
+ * `ValidationError` (HTTP 400) whose message never echoes the cursor. An
+ * invalid `secret` is a programming error and still throws `TypeError`.
  */
 export function decodeCursor(cursor, options = {}) {
     if (typeof cursor !== "string" || cursor.trim().length === 0) {
-        throw new TypeError("A cursor value is required.");
+        throw createInvalidCursorError("A cursor value is required.", "cursor_required");
     }
     let payload = cursor;
     if (options.secret !== undefined) {
         validateSecret(options.secret);
         const separator = cursor.lastIndexOf(CURSOR_SIGNATURE_SEPARATOR);
         if (separator <= 0) {
-            throw new TypeError("Invalid pagination cursor signature.");
+            throw createInvalidCursorError("Invalid pagination cursor signature.", "cursor_signature");
         }
         payload = cursor.slice(0, separator);
         const signature = cursor.slice(separator + 1);
         const expected = signCursor(payload, options.secret);
         if (signature.length !== expected.length ||
             !timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
-            throw new TypeError("Invalid pagination cursor signature.");
+            throw createInvalidCursorError("Invalid pagination cursor signature.", "cursor_signature");
         }
     }
     let decoded;
@@ -238,9 +243,7 @@ export function decodeCursor(cursor, options = {}) {
         decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
     }
     catch (error) {
-        throw new TypeError("Invalid pagination cursor.", {
-            cause: error,
-        });
+        throw createInvalidCursorError("Invalid pagination cursor.", "cursor_malformed", error);
     }
     if (options.allowedFields !== undefined) {
         validateCursorPayload(decoded, options.allowedFields);
@@ -253,18 +256,18 @@ export function decodeCursor(cursor, options = {}) {
  */
 export function validateCursorPayload(value, allowedFields) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw new TypeError("Pagination cursor payload must be an object.");
+        throw createInvalidCursorError("Pagination cursor payload must be an object.", "cursor_payload");
     }
     const allowed = new Set(allowedFields);
     for (const [key, entry] of Object.entries(value)) {
         if (FORBIDDEN_CURSOR_KEYS.has(key) || !allowed.has(key)) {
-            throw new TypeError(`Pagination cursor contains an unexpected field "${key}".`);
+            throw createInvalidCursorError("Pagination cursor contains an unexpected field.", "cursor_field");
         }
         if (entry !== null &&
             typeof entry !== "string" &&
             typeof entry !== "number" &&
             typeof entry !== "boolean") {
-            throw new TypeError(`Pagination cursor field "${key}" must be a primitive value.`);
+            throw createInvalidCursorError("Pagination cursor fields must be primitive values.", "cursor_payload");
         }
     }
 }

package/dist/pagination/pagination.cursorError.d.ts

@@ -0,0 +1,17 @@
+import { ValidationError } from "@zudojs/errors";
+/**
+ * Why a client-supplied pagination cursor was rejected. Carried as the
+ * `code` of the single issue on the thrown `ValidationError`.
+ */
+export type InvalidCursorReason = "cursor_required" | "cursor_signature" | "cursor_malformed" | "cursor_payload" | "cursor_field";
+/**
+ * Creates the error thrown for a missing, forged, tampered or malformed
+ * pagination cursor.
+ *
+ * A cursor is client input, so a bad one is a `ValidationError` (HTTP 400,
+ * exposable) rather than a `TypeError` that an HTTP layer would turn into a
+ * 500. Messages never echo the cursor or its contents, and the decoding
+ * failure is kept only as the non-exposed `cause`.
+ */
+export declare function createInvalidCursorError(message: string, reason: InvalidCursorReason, cause?: unknown): ValidationError;
+//# sourceMappingURL=pagination.cursorError.d.ts.map

package/dist/pagination/pagination.cursorError.js

@@ -0,0 +1,17 @@
+import { ValidationError } from "@zudojs/errors";
+/**
+ * Creates the error thrown for a missing, forged, tampered or malformed
+ * pagination cursor.
+ *
+ * A cursor is client input, so a bad one is a `ValidationError` (HTTP 400,
+ * exposable) rather than a `TypeError` that an HTTP layer would turn into a
+ * 500. Messages never echo the cursor or its contents, and the decoding
+ * failure is kept only as the non-exposed `cause`.
+ */
+export function createInvalidCursorError(message, reason, cause) {
+    return new ValidationError(message, {
+        issues: [{ field: "cursor", path: ["cursor"], code: reason, message }],
+        ...(cause !== undefined ? { cause } : {}),
+    });
+}
+//# sourceMappingURL=pagination.cursorError.js.map

package/dist/pagination/pagination.keyset.d.ts

@@ -1,5 +1,6 @@
 import type { SortInput } from "../databaseType/databaseType.type.js";
 import { type CursorPaginatedResult, type CursorPayload } from "./pagination.core.js";
+import { type KeysetDirection } from "./pagination.keysetDirection.js";
 /**
  * Options for building a keyset page.
  */
@@ -21,6 +22,13 @@ export interface KeysetPageOptions<TField extends string = string> {
      * Secret used to sign cursors. Strongly recommended for public APIs.
      */
     readonly secret?: string;
+    /**
+     * Direction the page was fetched in (default `"forward"`). Use
+     * `getKeysetDirection` on the decoded cursor. A backward page must be
+     * fetched with `keysetFetchSort(sort, "backward")`; its rows are put
+     * back into `sort` order here.
+     */
+    readonly direction?: KeysetDirection;
 }
 /**
  * A Prisma-style filter object produced by the keyset helpers.
@@ -29,27 +37,36 @@ export type KeysetWhere = Readonly<Record<string, unknown>>;
 /**
  * Decodes and validates a keyset cursor against the sort definition.
  *
- * The payload may only contain the sort fields and primitive values.
+ * The payload may only contain the sort fields and primitive values (plus
+ * the backward marker of a `previousCursor`). A forged, tampered or
+ * malformed cursor throws a `ValidationError` (HTTP 400).
  */
 export declare function decodeKeysetCursor<TField extends string = string>(cursor: string, sort: readonly SortInput<TField>[], secret?: string): CursorPayload;
 /**
  * Builds a Prisma-compatible `where` fragment that selects the rows that
- * come strictly after the cursor position in the given sort order.
+ * come strictly after the cursor position in the given sort order, or
+ * strictly before it for a backward cursor (a `previousCursor`).
  *
- * For a sort of `[a asc, b desc]` the result is
+ * For a sort of `[a asc, b desc]` the forward result is
  * `OR: [{ a: { gt: A } }, { AND: [{ a: A }, { b: { lt: B } }] }]`.
  */
 export declare function buildKeysetWhere<TField extends string = string>(cursor: CursorPayload, sort: readonly SortInput<TField>[]): KeysetWhere;
 /**
- * Derives the cursor payload for a row from the sort fields.
+ * Derives the cursor payload for a row from the sort fields. A
+ * `"backward"` cursor selects the rows before `row` instead of after it.
  */
-export declare function createKeysetCursor<TField extends string = string>(row: Readonly<Record<string, unknown>>, sort: readonly SortInput<TField>[], secret?: string): string;
+export declare function createKeysetCursor<TField extends string = string>(row: Readonly<Record<string, unknown>>, sort: readonly SortInput<TField>[], secret?: string, direction?: KeysetDirection): string;
 /**
  * Turns `limit + 1` fetched rows into a cursor-paginated result.
  *
- * Fetch `limit + 1` rows ordered by `sort`, then pass them here: the extra
- * row signals a next page and is dropped, and `nextCursor` is derived from
- * the last returned row.
+ * Fetch `limit + 1` rows ordered by `keysetFetchSort(sort, direction)`,
+ * then pass them here: the extra row signals another page in the fetch
+ * direction and is dropped. `nextCursor` is derived from the last returned
+ * row and `previousCursor` from the first, so a client can page both ways.
+ *
+ * Forward: `previousCursor` is set whenever the page was requested with a
+ * cursor and is not empty. Backward: `nextCursor` is always set for a
+ * non-empty page, and `previousCursor` only when more rows precede it.
  */
 export declare function createKeysetPage<TEntity extends Readonly<Record<string, unknown>>, TField extends string = string>(rows: readonly TEntity[], options: KeysetPageOptions<TField>): CursorPaginatedResult<TEntity>;
 //# sourceMappingURL=pagination.keyset.d.ts.map

package/dist/pagination/pagination.keyset.js

@@ -1,35 +1,45 @@
 import { createCursorPaginatedResult, decodeCursor, encodeCursor, normalizeLimit, } from "./pagination.core.js";
+import { createInvalidCursorError } from "./pagination.cursorError.js";
+import { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, } from "./pagination.keysetDirection.js";
 /**
  * Decodes and validates a keyset cursor against the sort definition.
  *
- * The payload may only contain the sort fields and primitive values.
+ * The payload may only contain the sort fields and primitive values (plus
+ * the backward marker of a `previousCursor`). A forged, tampered or
+ * malformed cursor throws a `ValidationError` (HTTP 400).
  */
 export function decodeKeysetCursor(cursor, sort, secret) {
     validateSort(sort);
     const payload = decodeCursor(cursor, {
         secret,
-        allowedFields: sort.map((entry) => entry.field),
+        allowedFields: [...sort.map((entry) => entry.field), KEYSET_BACKWARD_KEY],
     });
     for (const entry of sort) {
-        if (!(entry.field in payload)) {
-            throw new TypeError(`Pagination cursor is missing sort field "${entry.field}".`);
+        if (!Object.hasOwn(payload, entry.field)) {
+            throw createInvalidCursorError(`Pagination cursor is missing sort field "${entry.field}".`, "cursor_field");
         }
     }
+    const marker = payload[KEYSET_BACKWARD_KEY];
+    if (marker !== undefined && marker !== true) {
+        throw createInvalidCursorError("Pagination cursor fields must be primitive values.", "cursor_payload");
+    }
     return payload;
 }
 /**
  * Builds a Prisma-compatible `where` fragment that selects the rows that
- * come strictly after the cursor position in the given sort order.
+ * come strictly after the cursor position in the given sort order, or
+ * strictly before it for a backward cursor (a `previousCursor`).
  *
- * For a sort of `[a asc, b desc]` the result is
+ * For a sort of `[a asc, b desc]` the forward result is
  * `OR: [{ a: { gt: A } }, { AND: [{ a: A }, { b: { lt: B } }] }]`.
  */
 export function buildKeysetWhere(cursor, sort) {
     validateSort(sort);
     const branches = [];
-    sort.forEach((entry, index) => {
+    const effective = getKeysetDirection(cursor) === "backward" ? reverseKeysetSort(sort) : sort;
+    effective.forEach((entry, index) => {
         const comparison = entry.direction === "desc" ? "lt" : "gt";
-        const conditions = sort
+        const conditions = effective
             .slice(0, index)
             .map((previous) => ({
             [previous.field]: { equals: cursor[previous.field] },
@@ -42,34 +52,52 @@ export function buildKeysetWhere(cursor, sort) {
     return branches.length === 1 ? branches[0] : { OR: branches };
 }
 /**
- * Derives the cursor payload for a row from the sort fields.
+ * Derives the cursor payload for a row from the sort fields. A
+ * `"backward"` cursor selects the rows before `row` instead of after it.
  */
-export function createKeysetCursor(row, sort, secret) {
+export function createKeysetCursor(row, sort, secret, direction = "forward") {
     validateSort(sort);
     const payload = {};
     for (const entry of sort) {
         payload[entry.field] = toCursorValue(row[entry.field], entry.field);
     }
+    if (direction === "backward") {
+        payload[KEYSET_BACKWARD_KEY] = true;
+    }
     return encodeCursor(payload, { secret });
 }
 /**
  * Turns `limit + 1` fetched rows into a cursor-paginated result.
  *
- * Fetch `limit + 1` rows ordered by `sort`, then pass them here: the extra
- * row signals a next page and is dropped, and `nextCursor` is derived from
- * the last returned row.
+ * Fetch `limit + 1` rows ordered by `keysetFetchSort(sort, direction)`,
+ * then pass them here: the extra row signals another page in the fetch
+ * direction and is dropped. `nextCursor` is derived from the last returned
+ * row and `previousCursor` from the first, so a client can page both ways.
+ *
+ * Forward: `previousCursor` is set whenever the page was requested with a
+ * cursor and is not empty. Backward: `nextCursor` is always set for a
+ * non-empty page, and `previousCursor` only when more rows precede it.
  */
 export function createKeysetPage(rows, options) {
     const limit = normalizeLimit(options.limit);
-    const hasNextPage = rows.length > limit;
-    const data = rows.slice(0, limit);
+    const backward = options.direction === "backward";
+    const hasMore = rows.length > limit;
+    const page = rows.slice(0, limit);
+    const data = backward ? page.reverse() : page;
+    const first = data[0];
     const last = data[data.length - 1];
+    const hasCursor = options.cursor !== undefined && options.cursor !== null;
+    const hasNextPage = backward ? hasCursor : hasMore;
+    const hasPreviousPage = backward ? hasMore : hasCursor;
     return createCursorPaginatedResult(data, limit, {
         hasNextPage,
-        hasPreviousPage: options.cursor !== undefined && options.cursor !== null,
+        hasPreviousPage,
         nextCursor: hasNextPage && last
             ? createKeysetCursor(last, options.sort, options.secret)
             : null,
+        previousCursor: hasPreviousPage && first
+            ? createKeysetCursor(first, options.sort, options.secret, "backward")
+            : null,
     });
 }
 function toCursorValue(value, field) {

package/dist/pagination/pagination.keysetDirection.d.ts

@@ -0,0 +1,29 @@
+import type { SortInput } from "../databaseType/databaseType.type.js";
+import type { CursorPayload } from "./pagination.core.js";
+/**
+ * Direction a keyset cursor pages in. A `nextCursor` pages forward (rows
+ * after the cursor position); a `previousCursor` pages backward (rows
+ * before it).
+ */
+export type KeysetDirection = "forward" | "backward";
+/**
+ * Reserved cursor payload key marking a backward cursor. It can never
+ * collide with a sort field, because sort fields must be identifiers.
+ */
+export declare const KEYSET_BACKWARD_KEY = "$before";
+/**
+ * Returns the direction a decoded keyset cursor pages in.
+ */
+export declare function getKeysetDirection(cursor: CursorPayload): KeysetDirection;
+/**
+ * Flips every direction in a sort definition. A backward page is fetched
+ * with the reversed sort (so the rows nearest the cursor come first) and
+ * then put back into the requested order by `createKeysetPage`.
+ */
+export declare function reverseKeysetSort<TField extends string>(sort: readonly SortInput<TField>[]): readonly SortInput<TField>[];
+/**
+ * Returns the sort a page must be fetched with for the given direction:
+ * the requested sort going forward, the reversed sort going backward.
+ */
+export declare function keysetFetchSort<TField extends string>(sort: readonly SortInput<TField>[], direction: KeysetDirection): readonly SortInput<TField>[];
+//# sourceMappingURL=pagination.keysetDirection.d.ts.map

package/dist/pagination/pagination.keysetDirection.js

@@ -0,0 +1,30 @@
+/**
+ * Reserved cursor payload key marking a backward cursor. It can never
+ * collide with a sort field, because sort fields must be identifiers.
+ */
+export const KEYSET_BACKWARD_KEY = "$before";
+/**
+ * Returns the direction a decoded keyset cursor pages in.
+ */
+export function getKeysetDirection(cursor) {
+    return cursor[KEYSET_BACKWARD_KEY] === true ? "backward" : "forward";
+}
+/**
+ * Flips every direction in a sort definition. A backward page is fetched
+ * with the reversed sort (so the rows nearest the cursor come first) and
+ * then put back into the requested order by `createKeysetPage`.
+ */
+export function reverseKeysetSort(sort) {
+    return sort.map((entry) => ({
+        ...entry,
+        direction: entry.direction === "desc" ? "asc" : "desc",
+    }));
+}
+/**
+ * Returns the sort a page must be fetched with for the given direction:
+ * the requested sort going forward, the reversed sort going backward.
+ */
+export function keysetFetchSort(sort, direction) {
+    return direction === "backward" ? reverseKeysetSort(sort) : sort;
+}
+//# sourceMappingURL=pagination.keysetDirection.js.map

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

@@ -177,6 +177,11 @@ export declare abstract class BaseRepository<TEntity, TId = string, TCreateInput
      * tiebreaker), `limit + 1` rows are fetched and the extra row decides
      * `hasNextPage`. Cursors are validated against the sort fields and, when
      * `cursorSecret` is configured, signed.
+     *
+     * Pass `meta.nextCursor` to page forward and `meta.previousCursor` to
+     * page backward; both come back in `options.sort` order. A forged,
+     * tampered or malformed cursor rejects with a `ValidationError` (400)
+     * before any query runs.
      */
     paginateCursor<TField extends string = string>(filter?: TWhereInput, options?: CursorQueryOptions<TField>): Promise<CursorPaginatedResult<TEntity>>;
     /**

package/dist/repository/repository.base.js

@@ -1,6 +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 { getKeysetDirection, keysetFetchSort, } from "../pagination/pagination.keysetDirection.js";
 import { toPrismaArgs, toPrismaOrderBy, } from "../queryBuilder/queryBuilder.prisma.js";
 import { createAbortError, createTimeoutError, mapRepositoryError, } from "./repository.errors.js";
 const DEFAULT_SOFT_DELETE_FIELD = "deletedAt";
@@ -151,21 +152,28 @@ export class BaseRepository {
      * tiebreaker), `limit + 1` rows are fetched and the extra row decides
      * `hasNextPage`. Cursors are validated against the sort fields and, when
      * `cursorSecret` is configured, signed.
+     *
+     * Pass `meta.nextCursor` to page forward and `meta.previousCursor` to
+     * page backward; both come back in `options.sort` order. A forged,
+     * tampered or malformed cursor rejects with a `ValidationError` (400)
+     * before any query runs.
      */
     async paginateCursor(filter, options) {
         if (filter !== undefined) {
             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);
+        let direction = "forward";
         if (cursor !== null) {
             const payload = decodeKeysetCursor(cursor, sort, this.cursorSecret);
+            direction = getKeysetDirection(payload);
             const keyset = buildKeysetWhere(payload, sort);
             where = where === undefined ? keyset : { AND: [where, keyset] };
         }
+        const orderBy = this.buildOrderBy(keysetFetchSort(sort, direction));
         const rows = await this.execute("paginateCursor", () => this.delegate.findMany({
             where: where,
             take: limit + 1,
@@ -176,6 +184,7 @@ export class BaseRepository {
             limit,
             cursor,
             secret: this.cursorSecret,
+            direction,
         });
     }
     /**

package/dist/transaction/transaction.core.d.ts

@@ -77,9 +77,14 @@ export declare class TransactionManager {
      * Executes a callback inside a managed transaction and returns the
      * result together with the final context (`status: "committed"`).
      *
-     * On failure the thrown `DatabaseError` carries `transactionId`,
-     * `transactionStatus: "failed"` and the supplied metadata; use
-     * {@link getTransactionContextFromError} to recover the context.
+     * On a database failure the thrown `DatabaseError` carries
+     * `transactionId`, `transactionStatus: "failed"` and the supplied
+     * metadata; use {@link getTransactionContextFromError} to recover the
+     * context.
+     *
+     * A non-database `BaseError` thrown by the callback (for example a
+     * `NotFoundError` or `DomainError`) rolls the transaction back and is
+     * rethrown as the same, unmodified instance.
      */
     run<TResult>(callback: (transaction: DatabaseTransactionContext, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TransactionOutcome<TResult>>;
     /**
@@ -93,6 +98,11 @@ export declare class TransactionManager {
 export declare function createTransactionManager(client: DatabaseClient): TransactionManager;
 /**
  * Executes a managed database transaction.
+ *
+ * The transaction rolls back when the callback throws. A `@zudojs/errors`
+ * `BaseError` that is not a `DatabaseError` (domain, application,
+ * validation, not-found, ...) propagates unchanged; driver and database
+ * failures and any other thrown value become a `DatabaseError`.
  */
 export declare function withTransaction<TResult>(client: DatabaseClient, callback: (transaction: DatabaseTransactionContext, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TResult>;
 /**

package/dist/transaction/transaction.core.js

@@ -1,5 +1,5 @@
 import { DatabaseOperation } from "@zudojs/errors";
-import { isDatabaseErrorLike, isRetryableTransactionError, normalizeDatabaseError, withDatabaseErrorMetadata, } from "../databaseClient/databaseClient.errors.js";
+import { isDatabaseErrorLike, isNonDatabaseBaseError, isRetryableTransactionError, normalizeDatabaseError, withDatabaseErrorMetadata, } from "../databaseClient/databaseClient.errors.js";
 import { computeRetryDelay } from "./transaction.backoff.js";
 /**
  * Generates a transaction identifier.
@@ -33,9 +33,14 @@ export class TransactionManager {
      * Executes a callback inside a managed transaction and returns the
      * result together with the final context (`status: "committed"`).
      *
-     * On failure the thrown `DatabaseError` carries `transactionId`,
-     * `transactionStatus: "failed"` and the supplied metadata; use
-     * {@link getTransactionContextFromError} to recover the context.
+     * On a database failure the thrown `DatabaseError` carries
+     * `transactionId`, `transactionStatus: "failed"` and the supplied
+     * metadata; use {@link getTransactionContextFromError} to recover the
+     * context.
+     *
+     * A non-database `BaseError` thrown by the callback (for example a
+     * `NotFoundError` or `DomainError`) rolls the transaction back and is
+     * rethrown as the same, unmodified instance.
      */
     async run(callback, options = {}) {
         if (typeof callback !== "function") {
@@ -48,6 +53,8 @@ export class TransactionManager {
             return { result, context: withStatus(base, "committed") };
         }
         catch (error) {
+            if (isNonDatabaseBaseError(error))
+                throw error;
             const failed = withStatus(base, "failed");
             throw attachTransactionContext(normalizeDatabaseError(error, {
                 operation: DatabaseOperation.TRANSACTION,
@@ -70,6 +77,11 @@ export function createTransactionManager(client) {
 }
 /**
  * Executes a managed database transaction.
+ *
+ * The transaction rolls back when the callback throws. A `@zudojs/errors`
+ * `BaseError` that is not a `DatabaseError` (domain, application,
+ * validation, not-found, ...) propagates unchanged; driver and database
+ * failures and any other thrown value become a `DatabaseError`.
  */
 export async function withTransaction(client, callback, options) {
     return createTransactionManager(client).execute(callback, options);

package/dist/unitOfWork/unitOfWork.core.js

@@ -1,5 +1,5 @@
 import { DatabaseOperation } from "@zudojs/errors";
-import { normalizeDatabaseError } from "../databaseClient/databaseClient.errors.js";
+import { isNonDatabaseBaseError, normalizeDatabaseError, } from "../databaseClient/databaseClient.errors.js";
 /**
  * Prisma-backed unit of work.
  */
@@ -23,6 +23,8 @@ export class DatabaseUnitOfWork {
                 return await callback(transaction);
             }
             catch (error) {
+                if (isNonDatabaseBaseError(error))
+                    throw error;
                 throw normalizeDatabaseError(error, {
                     operation: DatabaseOperation.TRANSACTION,
                     fallbackMessage: "Unit of work execution failed.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/database",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Database abstraction layer with clients, repositories, transactions, and query building for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -41,9 +41,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/logger": "1.3.0",
-    "@zudojs/types": "1.1.1"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/logger": "1.4.0",
+    "@zudojs/types": "1.2.0"
   },
   "peerDependencies": {
     "@prisma/client": ">=7.0.0 <8"
@@ -52,7 +52,7 @@
     "@prisma/client": "7.10.0",
     "prisma": "7.10.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -67,7 +67,7 @@
     "query",
     "transactions"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-database",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },