@zudojs/database 0.1.0 → 1.1.0

package/dist/health/health.check.js

@@ -1,9 +1,35 @@
-import { DatabaseError } from "@zudojs/errors";
-import { Prisma } from "@prisma/client";
+import { DatabaseError, DatabaseOperation, ErrorCode } from "@zudojs/errors";
+import { isDatabaseErrorLike, normalizeDatabaseError, } from "../databaseClient/databaseClient.errors.js";
 /**
  * Default database health-check timeout.
  */
 export const DEFAULT_HEALTH_TIMEOUT_MS = 5_000;
+/**
+ * Error raised by {@link assertDatabaseHealth}. The underlying failure is
+ * preserved as `cause`.
+ */
+export class DatabaseUnhealthyError extends DatabaseError {
+    health;
+    constructor(health, cause) {
+        super("Database health check failed.", {
+            code: ErrorCode.DATABASE_CONNECTION,
+            statusCode: 503,
+            operation: DatabaseOperation.CONNECT,
+            metadata: {
+                status: health.status,
+                latencyMs: health.latencyMs,
+                checkedAt: health.checkedAt.toISOString(),
+                ...(health.error?.code ? { errorCode: health.error.code } : {}),
+                ...(health.error?.databaseCode
+                    ? { databaseCode: health.error.databaseCode }
+                    : {}),
+            },
+            cause,
+        });
+        this.name = "DatabaseUnhealthyError";
+        this.health = health;
+    }
+}
 /**
  * Performs a lightweight database health check.
  */
@@ -16,7 +42,7 @@ export async function checkDatabaseHealth(client, options = {}) {
     const startedAt = performance.now();
     try {
         await withTimeout(executeHealthCheck(client), timeoutMs);
-        const latencyMs = Math.max(0, Math.round(performance.now() - startedAt));
+        const latencyMs = elapsed(startedAt);
         return {
             status: latencyMs > timeoutMs * 0.75 ? "degraded" : "healthy",
             healthy: true,
@@ -26,9 +52,9 @@ export async function checkDatabaseHealth(client, options = {}) {
         };
     }
     catch (error) {
-        const latencyMs = Math.max(0, Math.round(performance.now() - startedAt));
+        const latencyMs = elapsed(startedAt);
         const normalizedError = normalizeHealthError(error);
-        return {
+        const health = {
             status: "unhealthy",
             healthy: false,
             latencyMs,
@@ -36,8 +62,22 @@ export async function checkDatabaseHealth(client, options = {}) {
             message: normalizedError.message,
             error: normalizedError,
         };
+        Object.defineProperty(health, HEALTH_CAUSE, { value: error, enumerable: false });
+        return health;
     }
 }
+/**
+ * Symbol under which the original failure is kept on an unhealthy result.
+ * It is a non-enumerable symbol key, so serialised health output never
+ * includes it.
+ */
+const HEALTH_CAUSE = Symbol("zudojs.database.healthCause");
+/**
+ * Returns the original error that made a health check fail, if any.
+ */
+export function getHealthCheckCause(health) {
+    return health[HEALTH_CAUSE];
+}
 /**
  * Performs a database readiness check.
  *
@@ -53,38 +93,30 @@ export async function checkDatabaseReadiness(client, options = {}) {
     const startedAt = performance.now();
     try {
         await withTimeout(executeHealthCheck(client), timeoutMs);
-        const latencyMs = Math.max(0, Math.round(performance.now() - startedAt));
         return {
             ready: true,
             checkedAt,
-            latencyMs,
+            latencyMs: elapsed(startedAt),
             message: "Database is ready.",
         };
     }
     catch (error) {
-        const latencyMs = Math.max(0, Math.round(performance.now() - startedAt));
         return {
             ready: false,
             checkedAt,
-            latencyMs,
+            latencyMs: elapsed(startedAt),
             message: normalizeHealthError(error).message,
         };
     }
 }
 /**
- * Throws when the database is not healthy.
+ * Throws a {@link DatabaseUnhealthyError} (with the real failure as
+ * `cause`) when the database is not healthy.
  */
 export async function assertDatabaseHealth(client, options = {}) {
     const health = await checkDatabaseHealth(client, options);
     if (!health.healthy) {
-        throw new DatabaseError("Database health check failed.", {
-            metadata: {
-                status: health.status,
-                latencyMs: health.latencyMs,
-                checkedAt: health.checkedAt.toISOString(),
-            },
-            cause: health.error ? new Error(health.error.message) : undefined,
-        });
+        throw new DatabaseUnhealthyError(health, getHealthCheckCause(health));
     }
     return health;
 }
@@ -96,21 +128,12 @@ export async function isDatabaseHealthy(client, options = {}) {
     return health.healthy;
 }
 /**
- * Executes the lightweight health query.
+ * Executes the lightweight health query. Errors are already normalised by
+ * the client, so they are passed through unchanged.
  */
 async function executeHealthCheck(client) {
-    try {
-        await client.queryRaw(Prisma.sql `SELECT 1 AS result`);
-    }
-    catch (error) {
-        throw new DatabaseError("Database health query failed.", {
-            cause: error,
-        });
-    }
+    await client.queryRawUnsafe("SELECT 1 AS result");
 }
-/**
- * Runs a promise with a timeout.
- */
 async function withTimeout(promise, timeoutMs) {
     let timeout;
     try {
@@ -118,42 +141,50 @@ async function withTimeout(promise, timeoutMs) {
             promise,
             new Promise((_resolve, reject) => {
                 timeout = setTimeout(() => {
-                    reject(new DatabaseError(`Database health check timed out after ${timeoutMs}ms.`));
+                    reject(new DatabaseError(`Database health check timed out after ${timeoutMs}ms.`, {
+                        code: ErrorCode.DATABASE_TIMEOUT,
+                        statusCode: 503,
+                        operation: DatabaseOperation.QUERY,
+                        metadata: { timeoutMs },
+                    }));
                 }, timeoutMs);
             }),
         ]);
     }
     finally {
-        if (timeout) {
+        if (timeout)
             clearTimeout(timeout);
-        }
     }
 }
-/**
- * Normalizes timeout values.
- */
 function normalizeTimeout(timeoutMs) {
-    if (timeoutMs === undefined) {
+    if (timeoutMs === undefined)
         return DEFAULT_HEALTH_TIMEOUT_MS;
-    }
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         throw new TypeError("Database health timeout must be a positive finite number.");
     }
     return Math.floor(timeoutMs);
 }
+function elapsed(startedAt) {
+    return Math.max(0, Math.round(performance.now() - startedAt));
+}
 /**
- * Converts an unknown error into a safe health error.
+ * Converts an unknown error into a safe health error. Prisma errors are
+ * mapped so connection failures never leak host names.
  */
 function normalizeHealthError(error) {
-    if (error instanceof Error) {
-        return {
-            name: error.name,
-            message: error.message,
-        };
-    }
+    const normalized = isDatabaseErrorLike(error)
+        ? error
+        : normalizeDatabaseError(error, {
+            operation: DatabaseOperation.QUERY,
+            fallbackMessage: "Database health check failed.",
+        });
     return {
-        name: "DatabaseHealthError",
-        message: "Database health check failed.",
+        name: normalized.name,
+        message: normalized.message,
+        code: String(normalized.code),
+        ...(normalized.databaseCode !== undefined
+            ? { databaseCode: String(normalized.databaseCode) }
+            : {}),
     };
 }
 //# sourceMappingURL=health.check.js.map

package/dist/health/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Database health and readiness monitoring.
  */
-export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, DEFAULT_HEALTH_TIMEOUT_MS, type DatabaseHealthStatus, type DatabaseHealth, type DatabaseHealthOptions, type DatabaseReadiness, } from "./health.check.js";
+export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, getHealthCheckCause, DatabaseUnhealthyError, DEFAULT_HEALTH_TIMEOUT_MS, type DatabaseHealthStatus, type DatabaseHealth, type DatabaseHealthOptions, type DatabaseReadiness, } from "./health.check.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/health/index.js

@@ -3,5 +3,5 @@
  *
  * Database health and readiness monitoring.
  */
-export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, DEFAULT_HEALTH_TIMEOUT_MS, } from "./health.check.js";
+export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, getHealthCheckCause, DatabaseUnhealthyError, DEFAULT_HEALTH_TIMEOUT_MS, } from "./health.check.js";
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -16,21 +16,21 @@
  *   • Seed management
  *   • Health and readiness checks
  */
-export type { DatabaseOperationOptions, DatabaseStatus, TransactionIsolationLevel, DatabaseOperation, DatabaseConnectionOptions, DatabaseHealth as DatabaseHealthInfo, DatabaseMetrics, TransactionOptions, TransactionCallback, Repository, PaginationInput, PaginationMeta, PaginatedResult, SortDirection, SortInput, QueryOptions, DatabaseEntity, SoftDeletableEntity, AuditableEntity, DatabaseErrorInfo, DatabaseLogger, } from "./databaseType/index.js";
+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, createDatabaseClient, type DatabaseClientOptions, type DatabaseTransactionContext, } from "./databaseClient/index.js";
-export { DatabaseConnectionManager, createConnectionManager, type DatabaseConnectionEvent, type DatabaseConnectionListener, type DatabaseConnectionEventDetails, type DatabaseConnectionManagerOptions, } from "./databaseConnection/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 { 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, type RepositoryDelegate, type BaseRepositoryOptions, } from "./repository/index.js";
-export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, isTransactionActive, isTransactionCommitted, isTransactionFailed, type TransactionStatus, type TransactionContext, type ManagedTransactionOptions, } from "./transaction/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";
+export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, getTransactionContextFromError, isTransactionActive, isTransactionCommitted, isTransactionFailed, type TransactionStatus, type TransactionContext, type TransactionOutcome, type TransactionRetryOptions, type ManagedTransactionOptions, } from "./transaction/index.js";
 export { DatabaseUnitOfWork, createUnitOfWork, executeUnitOfWork, type UnitOfWork, type UnitOfWorkOptions, } from "./unitOfWork/index.js";
-export { QueryBuilder, createQueryBuilder, type QueryCondition, type QueryFilter, type QueryOperator, type QueryBuilderState, } 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, } from "./queryBuilder/index.js";
-export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, } from "./pagination/index.js";
-export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, isRelationType, isCollectionRelation, isSingleRelation, type RelationDefinition, type RelationType, type RelationLoadOptions, type RelationInclude, } from "./relations/index.js";
-export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, type DatabaseLockMode, type DatabaseLockOptions, type DatabaseLockResult, } from "./locks/index.js";
-export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, serializeCachePart, getOrSet, invalidateByPrefix, type CacheEntry, type CacheOptions, type CacheStats, type DatabaseCache, } from "./cache/index.js";
-export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, type Migration, type MigrationRecord, type MigrationResult, type MigrationStatus, type MigrationRunnerOptions, } from "./migration/index.js";
-export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, type Seed, type SeedRecord, type SeedResult, type SeedRunnerOptions, } from "./seed/index.js";
-export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, DEFAULT_HEALTH_TIMEOUT_MS, type DatabaseHealthStatus, type DatabaseHealth, type DatabaseHealthOptions, type DatabaseReadiness, } from "./health/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 { 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";
+export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, SQL_IDENTIFIER_PATTERN, validateIdentifier, validateLockKey, quoteIdentifier, hashLockKey, fnv1a64, getSqlDialect, isSqlDialectName, UnsupportedDialectError, DEFAULT_SQL_DIALECT, type Migration, type MigrationRecord, type MigrationResult, type MigrationStatus, type MigrationRunnerOptions, type RunnerTransactionOptions, type SqlDialect, type SqlDialectName, } from "./migration/index.js";
+export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, type Seed, type SeedRecord, type SeedResult, type SeedStatus, type SeedRunnerOptions, } from "./seed/index.js";
+export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, getHealthCheckCause, DatabaseUnhealthyError, DEFAULT_HEALTH_TIMEOUT_MS, type DatabaseHealthStatus, type DatabaseHealth, type DatabaseHealthOptions, type DatabaseReadiness, } from "./health/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -18,32 +18,32 @@
  */
 export { noopDatabaseLogger } from "./databaseType/index.js";
 // Client
-export { DatabaseClient, createDatabaseClient, } from "./databaseClient/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, } from "./databaseClient/index.js";
 // Connection
 export { DatabaseConnectionManager, createConnectionManager, } from "./databaseConnection/index.js";
 // Database facade
 export { Database, createDatabase, getDatabase, connectDatabase, disconnectDatabase, resetDatabase, } from "./database/index.js";
 // Repository
-export { BaseRepository, } from "./repository/index.js";
+export { BaseRepository, mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, } from "./repository/index.js";
 // Transactions
-export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, isTransactionActive, isTransactionCommitted, isTransactionFailed, } from "./transaction/index.js";
+export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, getTransactionContextFromError, isTransactionActive, isTransactionCommitted, isTransactionFailed, } from "./transaction/index.js";
 // Unit of Work
 export { DatabaseUnitOfWork, createUnitOfWork, executeUnitOfWork, } from "./unitOfWork/index.js";
 // Query Builder
-export { QueryBuilder, createQueryBuilder, } 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, } from "./queryBuilder/index.js";
+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, 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, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination/index.js";
 // Relations
-export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, isRelationType, isCollectionRelation, isSingleRelation, } from "./relations/index.js";
+export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, } from "./relations/index.js";
 // Locks
-export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, } from "./locks/index.js";
+export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, normalizeAdvisoryKeyPair, resolveLockTransactionOptions, } from "./locks/index.js";
 // Cache
-export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, serializeCachePart, getOrSet, invalidateByPrefix, } from "./cache/index.js";
+export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, escapeCachePart, serializeCachePart, getOrSet, invalidateByPrefix, CACHE_KEY_SEPARATOR, } from "./cache/index.js";
 // Migrations
-export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, } from "./migration/index.js";
+export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, SQL_IDENTIFIER_PATTERN, validateIdentifier, validateLockKey, quoteIdentifier, hashLockKey, fnv1a64, getSqlDialect, isSqlDialectName, UnsupportedDialectError, DEFAULT_SQL_DIALECT, } from "./migration/index.js";
 // Seeds
 export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, } from "./seed/index.js";
 // Health
-export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, DEFAULT_HEALTH_TIMEOUT_MS, } from "./health/index.js";
+export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, getHealthCheckCause, DatabaseUnhealthyError, DEFAULT_HEALTH_TIMEOUT_MS, } from "./health/index.js";
 //# sourceMappingURL=index.js.map

package/dist/locks/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @zudojs/database — Locks
  *
- * Advisory and row-level database locking.
+ * Advisory and row-level database locking (PostgreSQL).
  */
-export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, type DatabaseLockMode, type DatabaseLockOptions, type DatabaseLockResult, } from "./locks.core.js";
+export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, normalizeAdvisoryKeyPair, resolveLockTransactionOptions, type DatabaseLockMode, type DatabaseLockOptions, type DatabaseLockResult, } from "./locks.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/locks/index.js

@@ -1,7 +1,7 @@
 /**
  * @zudojs/database — Locks
  *
- * Advisory and row-level database locking.
+ * Advisory and row-level database locking (PostgreSQL).
  */
-export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, } from "./locks.core.js";
+export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, normalizeAdvisoryKeyPair, resolveLockTransactionOptions, } from "./locks.core.js";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,132 @@
+import type { DatabaseClient, DatabaseTransactionContext } from "../databaseClient/databaseClient.core.js";
+import type { TransactionOptions } from "../databaseType/databaseType.type.js";
+/**
+ * Supported row lock modes (PostgreSQL).
+ */
+export type DatabaseLockMode = "for-update" | "for-no-key-update" | "for-share" | "for-key-share";
+/**
+ * Options for acquiring a database lock.
+ *
+ * All locking in this module is PostgreSQL-specific (`pg_advisory_xact_lock`,
+ * `FOR UPDATE ... SKIP LOCKED`, `lock_timeout`).
+ */
+export interface DatabaseLockOptions {
+    /**
+     * Row lock mode. Ignored for advisory locks.
+     */
+    readonly mode?: DatabaseLockMode;
+    /**
+     * Maximum time to wait for the lock. Applied with
+     * `SET LOCAL lock_timeout` inside the transaction, so a contended lock
+     * fails with a lock-timeout error instead of Prisma's generic
+     * 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;
+    /**
+     * Row locks only: skip rows locked by other transactions instead of
+     * waiting. When the row is skipped the lock is *not* held and
+     * `acquired` is `false`.
+     */
+    readonly skipLocked?: boolean;
+    /**
+     * Fail immediately when the lock is held by another transaction.
+     */
+    readonly noWait?: boolean;
+    /**
+     * Advisory locks only: optional namespace. When supplied the two-int
+     * form `pg_advisory_xact_lock(int, int)` is used with the namespace
+     * hashed into the first argument, so unrelated services sharing one
+     * database cannot collide on the same 64-bit key space.
+     */
+    readonly namespace?: string;
+    /**
+     * Options forwarded to the transaction opened by the lock manager.
+     */
+    readonly transaction?: TransactionOptions;
+}
+/**
+ * Result of a lock acquisition.
+ */
+export interface DatabaseLockResult {
+    readonly acquired: boolean;
+    readonly lockKey: string;
+    readonly mode?: DatabaseLockMode;
+}
+/**
+ * Application-level lock abstraction for PostgreSQL.
+ *
+ * Locks are acquired inside a transaction and released when it ends.
+ */
+export declare class DatabaseLockManager {
+    private readonly client;
+    constructor(client: DatabaseClient);
+    /**
+     * Executes work inside a transaction after acquiring a PostgreSQL
+     * advisory transaction lock.
+     */
+    withAdvisoryLock<TResult>(lockKey: string, callback: (transaction: DatabaseTransactionContext) => Promise<TResult>, options?: DatabaseLockOptions): Promise<TResult>;
+    /**
+     * Acquires a row-level lock and executes work while holding it.
+     *
+     * @throws {DatabaseError} when the row does not exist or was skipped
+     * because another transaction holds it (`skipLocked`).
+     */
+    withRowLock<TResult>(tableName: string, id: string | number, callback: (transaction: DatabaseTransactionContext) => Promise<TResult>, options?: DatabaseLockOptions): Promise<TResult>;
+    /**
+     * Returns the underlying database client.
+     */
+    getClient(): DatabaseClient;
+}
+/**
+ * Creates a lock manager.
+ */
+export declare function createLockManager(client: DatabaseClient): DatabaseLockManager;
+/**
+ * Acquires a PostgreSQL advisory transaction lock.
+ *
+ * The lock key is hashed with FNV-1a to a signed 64-bit key (or, with a
+ * `namespace`, to a pair of signed 32-bit keys).
+ */
+export declare function acquireAdvisoryLock(transaction: DatabaseTransactionContext, lockKey: string, options?: DatabaseLockOptions): Promise<DatabaseLockResult>;
+/**
+ * Acquires a row-level PostgreSQL lock.
+ *
+ * @throws {DatabaseError} when the row does not exist.
+ * @returns `acquired: false` only when `skipLocked` skipped a row held by
+ * another transaction.
+ */
+export declare function lockRow(transaction: DatabaseTransactionContext, tableName: string, id: string | number, options?: DatabaseLockOptions): Promise<DatabaseLockResult>;
+/**
+ * Builds a safe PostgreSQL lock clause.
+ */
+export declare function buildLockClause(mode: DatabaseLockMode, options?: DatabaseLockOptions): string;
+/**
+ * Converts an application lock key into a deterministic signed 64-bit
+ * advisory key (FNV-1a 64).
+ */
+export declare function normalizeAdvisoryKey(lockKey: string): bigint;
+/**
+ * Converts a namespace and key into the two signed 32-bit integers used by
+ * the two-argument advisory lock functions.
+ */
+export declare function normalizeAdvisoryKeyPair(namespace: string, lockKey: string): readonly [number, number];
+/**
+ * Derives the transaction options for a lock so that `lock_timeout` is
+ * always shorter than the surrounding Prisma transaction timeout.
+ *
+ * Without this, a lock wait longer than Prisma's 5 s default would surface
+ * as a generic "transaction already closed" error instead of a lock
+ * timeout. When `transaction.timeoutMs` is not supplied it is raised to
+ * cover the lock wait plus the default budget for the callback.
+ *
+ * @throws {TypeError} when `transaction.timeoutMs` is explicitly shorter
+ * than `timeoutMs`.
+ */
+export declare function resolveLockTransactionOptions(options?: DatabaseLockOptions): TransactionOptions | undefined;
+//# sourceMappingURL=locks.core.d.ts.map