@zudojs/database 0.0.1 → 1.0.0

package/dist/databaseClient/databaseClient.errors.js

@@ -0,0 +1,425 @@
+/**
+ * @zudojs/database — Error normalisation
+ *
+ * Converts Prisma (and arbitrary) failures into `DatabaseError` instances
+ * that carry the Prisma error code as `databaseCode`, the operation that
+ * failed, and an HTTP-friendly status/code so callers can distinguish a
+ * unique violation from a missing row from an outage without reaching into
+ * `cause`.
+ *
+ * Prisma errors are detected structurally (a `code` such as `P2002` plus a
+ * `clientVersion`), so the mapping works regardless of which copy of
+ * `@prisma/client` produced the error.
+ */
+import { DatabaseError, DatabaseOperation, ErrorCategory, isDatabaseError, ErrorCode, } from "@zudojs/errors";
+/**
+ * Structural `DatabaseError` guard.
+ *
+ * `@zudojs/errors` resolves from the npm registry (exact `0.1.0` pins are a
+ * repo-wide convention), so a consumer may hold a second copy of the
+ * package. `instanceof` would then fail and errors would be double-wrapped;
+ * this guard accepts any `Error` that carries the `DatabaseError` shape
+ * (`category: "database"` plus a string `code`).
+ */
+export function isDatabaseErrorLike(value) {
+    if (isDatabaseError(value))
+        return true;
+    if (!(value instanceof Error))
+        return false;
+    const candidate = value;
+    return (candidate.category === ErrorCategory.DATABASE &&
+        typeof candidate.code === "string" &&
+        typeof candidate.statusCode === "number");
+}
+const CONNECTION_MESSAGE = "Database connection failed.";
+const PRISMA_CODE_MAP = Object.freeze({
+    // Query engine errors
+    P2000: {
+        kind: "validation",
+        statusCode: 400,
+        code: ErrorCode.DATABASE_QUERY,
+        message: "A value is too long for its column.",
+        expose: true,
+    },
+    P2002: {
+        kind: "conflict",
+        statusCode: 409,
+        code: ErrorCode.CONFLICT,
+        message: "A record with the same unique value already exists.",
+        expose: true,
+    },
+    P2003: {
+        kind: "constraint",
+        statusCode: 409,
+        code: ErrorCode.CONFLICT,
+        message: "A foreign key constraint was violated.",
+        expose: true,
+    },
+    P2004: {
+        kind: "constraint",
+        statusCode: 409,
+        code: ErrorCode.CONFLICT,
+        message: "A database constraint was violated.",
+        expose: true,
+    },
+    P2011: {
+        kind: "constraint",
+        statusCode: 400,
+        code: ErrorCode.DATABASE_QUERY,
+        message: "A required value was null.",
+        expose: true,
+    },
+    P2014: {
+        kind: "constraint",
+        statusCode: 409,
+        code: ErrorCode.CONFLICT,
+        message: "A required relation would be violated.",
+        expose: true,
+    },
+    P2015: {
+        kind: "not-found",
+        statusCode: 404,
+        code: ErrorCode.RESOURCE_NOT_FOUND,
+        message: "A related record could not be found.",
+        expose: true,
+    },
+    P2018: {
+        kind: "not-found",
+        statusCode: 404,
+        code: ErrorCode.RESOURCE_NOT_FOUND,
+        message: "Required connected records were not found.",
+        expose: true,
+    },
+    P2024: {
+        kind: "timeout",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_TIMEOUT,
+        message: "Timed out acquiring a database connection from the pool.",
+        expose: false,
+    },
+    P2025: {
+        kind: "not-found",
+        statusCode: 404,
+        code: ErrorCode.RESOURCE_NOT_FOUND,
+        message: "The requested record was not found.",
+        expose: true,
+    },
+    P2028: {
+        kind: "timeout",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_TRANSACTION,
+        message: "The database transaction timed out or was closed.",
+        expose: false,
+    },
+    P2034: {
+        kind: "serialization",
+        statusCode: 409,
+        code: ErrorCode.DATABASE_TRANSACTION,
+        message: "The transaction failed due to a write conflict or deadlock.",
+        expose: false,
+    },
+    // Connection / engine errors
+    P1000: {
+        kind: "connection",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_CONNECTION,
+        message: CONNECTION_MESSAGE,
+        expose: false,
+    },
+    P1001: {
+        kind: "connection",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_CONNECTION,
+        message: CONNECTION_MESSAGE,
+        expose: false,
+    },
+    P1002: {
+        kind: "timeout",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_TIMEOUT,
+        message: "The database server did not respond in time.",
+        expose: false,
+    },
+    P1003: {
+        kind: "connection",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_CONNECTION,
+        message: CONNECTION_MESSAGE,
+        expose: false,
+    },
+    P1008: {
+        kind: "timeout",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_TIMEOUT,
+        message: "The database operation timed out.",
+        expose: false,
+    },
+    P1010: {
+        kind: "connection",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_CONNECTION,
+        message: CONNECTION_MESSAGE,
+        expose: false,
+    },
+    P1011: {
+        kind: "connection",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_CONNECTION,
+        message: CONNECTION_MESSAGE,
+        expose: false,
+    },
+    P1017: {
+        kind: "connection",
+        statusCode: 503,
+        code: ErrorCode.DATABASE_CONNECTION,
+        message: "The database server closed the connection.",
+        expose: false,
+    },
+});
+/**
+ * Codes that indicate a transient transaction failure worth retrying.
+ */
+export const RETRYABLE_DATABASE_CODES = new Set([
+    "P2034", // Prisma: write conflict / deadlock
+    "P2028", // Prisma: transaction closed / timed out
+    "P1017", // Prisma: server closed the connection
+    "40001", // PostgreSQL: serialization_failure
+    "40P01", // PostgreSQL: deadlock_detected
+]);
+/**
+ * Detects a Prisma error structurally.
+ */
+export function isPrismaError(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    const code = candidate.code ?? candidate.errorCode;
+    return (typeof code === "string" &&
+        /^P\d{4}$/.test(code) &&
+        typeof candidate.clientVersion === "string");
+}
+/**
+ * Returns the Prisma / driver error code carried by an error, if any.
+ */
+export function getDatabaseErrorCode(error) {
+    if (isDatabaseErrorLike(error)) {
+        if (error.databaseCode !== undefined)
+            return String(error.databaseCode);
+        return getDatabaseErrorCode(error.cause);
+    }
+    if (isPrismaError(error)) {
+        return error.code ?? error.errorCode;
+    }
+    if (error && typeof error === "object") {
+        const code = error.code;
+        if (typeof code === "string" && code.length > 0)
+            return code;
+    }
+    return undefined;
+}
+/**
+ * Classifies a database error.
+ */
+export function getDatabaseErrorKind(error) {
+    const code = getDatabaseErrorCode(error);
+    if (code) {
+        const mapping = PRISMA_CODE_MAP[code];
+        if (mapping)
+            return mapping.kind;
+        if (code === "40001" || code === "40P01")
+            return "serialization";
+    }
+    if (isDatabaseErrorLike(error)) {
+        if (error.code === ErrorCode.DATABASE_CONNECTION)
+            return "connection";
+        if (error.code === ErrorCode.DATABASE_TIMEOUT)
+            return "timeout";
+        if (error.statusCode === 404)
+            return "not-found";
+        if (error.statusCode === 409)
+            return "conflict";
+    }
+    return "unknown";
+}
+/**
+ * Determines whether a transaction failure is safe to retry.
+ *
+ * Retrying re-runs the whole callback, so callbacks passed to
+ * `withTransactionRetry` must be idempotent outside the transaction.
+ */
+export function isRetryableTransactionError(error) {
+    const code = getDatabaseErrorCode(error);
+    if (code && RETRYABLE_DATABASE_CODES.has(code))
+        return true;
+    if (isPrismaError(error) && error.retryable === true)
+        return true;
+    return getDatabaseErrorKind(error) === "serialization";
+}
+/**
+ * Determines whether an error represents a unique-constraint conflict.
+ */
+export function isConflictError(error) {
+    const kind = getDatabaseErrorKind(error);
+    return kind === "conflict" || kind === "constraint";
+}
+/**
+ * Determines whether an error represents a missing record.
+ */
+export function isNotFoundError(error) {
+    return getDatabaseErrorKind(error) === "not-found";
+}
+/**
+ * Returns a copy of a `DatabaseError` with extra metadata, preserving
+ * `operation`, `driver` and `databaseCode` (which `BaseError.withMetadata`
+ * drops).
+ */
+export function withDatabaseErrorMetadata(error, metadata) {
+    return new DatabaseError(error.message, {
+        code: error.code,
+        category: error.category,
+        severity: error.severity,
+        statusCode: error.statusCode,
+        expose: error.expose,
+        isOperational: error.isOperational,
+        operation: error.operation,
+        driver: error.driver,
+        databaseCode: error.databaseCode,
+        metadata: { ...error.metadata, ...metadata },
+        cause: error.cause,
+    });
+}
+/**
+ * Converts any thrown value into a `DatabaseError`.
+ *
+ * Existing `DatabaseError`s are returned as-is unless `operation` or
+ * `metadata` need to be attached, in which case a copy carrying the extra
+ * information (and the original as `cause`) is returned. Prisma errors are
+ * mapped by code; connection failures get a fixed message so that host
+ * names from Prisma's messages are never exposed.
+ */
+export function normalizeDatabaseError(error, options = {}) {
+    const fallbackMessage = options.fallbackMessage ?? "A database operation failed.";
+    if (isDatabaseErrorLike(error)) {
+        // Subclasses (abort, unhealthy, unsupported dialect, ...) carry their
+        // identity in the class, and instances from another copy of
+        // @zudojs/errors must not be re-wrapped; only a plain DatabaseError from
+        // this copy is rebuilt with the extra information.
+        if (Object.getPrototypeOf(error) !== DatabaseError.prototype)
+            return error;
+        const needsOperation = options.operation !== undefined &&
+            error.operation === DatabaseOperation.UNKNOWN;
+        if (!needsOperation && !options.metadata)
+            return error;
+        return new DatabaseError(error.message, {
+            code: error.code,
+            category: error.category,
+            severity: error.severity,
+            statusCode: error.statusCode,
+            expose: error.expose,
+            isOperational: error.isOperational,
+            operation: needsOperation ? options.operation : error.operation,
+            driver: error.driver,
+            databaseCode: error.databaseCode,
+            metadata: { ...error.metadata, ...options.metadata },
+            cause: error.cause ?? error,
+        });
+    }
+    if (isPrismaError(error)) {
+        const databaseCode = (error.code ?? error.errorCode);
+        const mapping = PRISMA_CODE_MAP[databaseCode];
+        const meta = sanitizeMeta(error.meta);
+        if (mapping) {
+            return new DatabaseError(mapping.message, {
+                code: mapping.code,
+                statusCode: mapping.statusCode,
+                expose: mapping.expose,
+                operation: options.operation ?? inferOperation(mapping.kind),
+                driver: "prisma",
+                databaseCode,
+                metadata: { ...meta, ...options.metadata, kind: mapping.kind },
+                cause: error,
+            });
+        }
+        const isConnection = databaseCode.startsWith("P1");
+        return new DatabaseError(isConnection ? CONNECTION_MESSAGE : (error.message ?? fallbackMessage), {
+            code: isConnection ? ErrorCode.DATABASE_CONNECTION : ErrorCode.DATABASE,
+            statusCode: isConnection ? 503 : 500,
+            expose: false,
+            operation: options.operation ??
+                (isConnection ? DatabaseOperation.CONNECT : DatabaseOperation.UNKNOWN),
+            driver: "prisma",
+            databaseCode,
+            metadata: {
+                ...meta,
+                ...options.metadata,
+                kind: isConnection ? "connection" : "unknown",
+            },
+            cause: error,
+        });
+    }
+    const message = error instanceof Error && error.message.length > 0
+        ? error.message
+        : fallbackMessage;
+    return new DatabaseError(message, {
+        operation: options.operation ?? DatabaseOperation.UNKNOWN,
+        metadata: options.metadata,
+        cause: error,
+    });
+}
+function inferOperation(kind) {
+    switch (kind) {
+        case "connection":
+            return DatabaseOperation.CONNECT;
+        case "serialization":
+            return DatabaseOperation.TRANSACTION;
+        default:
+            return DatabaseOperation.QUERY;
+    }
+}
+/**
+ * Keeps only JSON-safe, non-sensitive fields from Prisma's `meta`.
+ */
+function sanitizeMeta(meta) {
+    const result = {};
+    if (!meta)
+        return result;
+    for (const key of ["modelName", "target", "field_name", "constraint", "cause"]) {
+        const value = meta[key];
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            result[key] = value;
+        }
+        else if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+            result[key] = Object.freeze([...value]);
+        }
+    }
+    return result;
+}
+/**
+ * Converts any failure into a plain, serialisable {@link DatabaseErrorInfo}
+ * (the shape exported for logging and API responses). The error is
+ * normalised first, so Prisma codes appear as `code`.
+ */
+export function toDatabaseErrorInfo(error, options = {}) {
+    const normalized = normalizeDatabaseError(error, options);
+    const metadata = normalized.metadata;
+    const model = metadata["model"] ?? metadata["modelName"];
+    const field = metadata["field"] ?? metadata["field_name"];
+    const constraint = metadata["constraint"] ?? metadata["target"];
+    return {
+        code: normalized.databaseCode !== undefined
+            ? String(normalized.databaseCode)
+            : String(normalized.code),
+        message: normalized.message,
+        operation: normalized.operation,
+        ...(typeof model === "string" ? { model } : {}),
+        ...(typeof field === "string" ? { field } : {}),
+        ...(typeof constraint === "string"
+            ? { constraint }
+            : Array.isArray(constraint)
+                ? { constraint: constraint.join(",") }
+                : {}),
+        cause: normalized.cause,
+        metadata,
+    };
+}
+//# sourceMappingURL=databaseClient.errors.js.map

package/dist/databaseClient/index.d.ts

@@ -3,5 +3,6 @@
  *
  * Prisma-backed database client and connection infrastructure.
  */
-export { DatabaseClient, createDatabaseClient, type DatabaseClientOptions, type DatabaseTransactionContext, } from "./databaseClient.core.js";
+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";
 //# sourceMappingURL=index.d.ts.map

package/dist/databaseClient/index.js

@@ -3,5 +3,6 @@
  *
  * Prisma-backed database client and connection infrastructure.
  */
-export { DatabaseClient, createDatabaseClient, } from "./databaseClient.core.js";
+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";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,163 @@
+import { DatabaseClient, type DatabaseClientOptions } from "../databaseClient/databaseClient.core.js";
+import { type DatabaseHealth as DetailedDatabaseHealth } from "../health/health.check.js";
+import type { DatabaseHealth, DatabaseStatus } from "../databaseType/databaseType.type.js";
+/**
+ * Connection lifecycle events.
+ */
+export type DatabaseConnectionEvent = "connecting" | "connected" | "disconnecting" | "disconnected" | "error" | "reconnecting";
+/**
+ * Listener invoked when the connection state changes.
+ */
+export type DatabaseConnectionListener = (event: DatabaseConnectionEvent, details: DatabaseConnectionEventDetails) => void;
+/**
+ * Details associated with a connection event.
+ */
+export interface DatabaseConnectionEventDetails {
+    readonly status: DatabaseStatus;
+    readonly timestamp: Date;
+    readonly error?: unknown;
+    readonly attempt?: number;
+}
+/**
+ * Reconnect policy applied after scheduled health checks fail.
+ */
+export interface DatabaseReconnectOptions {
+    /**
+     * Consecutive failed health checks before a reconnect is attempted.
+     * Defaults to 1.
+     */
+    readonly failureThreshold?: number;
+    /**
+     * Maximum reconnect attempts per outage. Defaults to 5.
+     */
+    readonly maxAttempts?: number;
+    /**
+     * Base delay between reconnect attempts; doubles each attempt up to
+     * `maxDelayMs`. Defaults to 500 ms.
+     */
+    readonly baseDelayMs?: number;
+    /**
+     * Upper bound for the backoff delay. Defaults to 30 000 ms.
+     */
+    readonly maxDelayMs?: number;
+}
+/**
+ * Options for the connection manager.
+ */
+export interface DatabaseConnectionManagerOptions extends DatabaseClientOptions {
+    /**
+     * Existing client to manage. When supplied the other client options are
+     * ignored, so one Prisma instance is never wrapped by two lifecycle
+     * state machines.
+     */
+    readonly client?: DatabaseClient;
+    readonly autoConnect?: boolean;
+    /**
+     * Interval for scheduled health checks. Disabled when omitted.
+     */
+    readonly healthCheckIntervalMs?: number;
+    /**
+     * Timeout for each scheduled health check. Defaults to the smaller of
+     * the interval and 5 000 ms.
+     */
+    readonly healthCheckTimeoutMs?: number;
+    /**
+     * Reconnect policy. Pass `false` to disable automatic reconnects.
+     */
+    readonly reconnect?: DatabaseReconnectOptions | false;
+}
+/**
+ * Manages the database connection lifecycle.
+ *
+ * The manager intentionally does not connect during construction.
+ * Application bootstrap should call `connect()` explicitly unless
+ * `autoConnect` is enabled.
+ */
+export declare class DatabaseConnectionManager {
+    private readonly client;
+    private readonly listeners;
+    private readonly autoConnect;
+    private readonly healthCheckIntervalMs?;
+    private readonly healthCheckTimeoutMs;
+    private readonly reconnect;
+    private healthCheckTimer?;
+    private healthCheckInFlight?;
+    private consecutiveFailures;
+    private reconnectPromise?;
+    private lastHealth?;
+    private destroyed;
+    constructor(options?: DatabaseConnectionManagerOptions);
+    /**
+     * Initializes the connection manager.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Opens the database connection. Concurrent calls share the client's
+     * in-flight attempt.
+     */
+    connect(): Promise<void>;
+    /**
+     * Closes the database connection.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Ensures that the connection is ready.
+     */
+    ensureConnected(): Promise<void>;
+    /**
+     * Returns the current connection status.
+     */
+    getStatus(): DatabaseStatus;
+    /**
+     * Performs a database health check (with the configured timeout).
+     */
+    healthCheck(): Promise<DatabaseHealth>;
+    /**
+     * Returns the result of the most recent scheduled health check.
+     */
+    getLastHealth(): DetailedDatabaseHealth | undefined;
+    /**
+     * Returns the underlying database client.
+     */
+    getClient(): DatabaseClient;
+    /**
+     * Subscribes to connection lifecycle events.
+     */
+    on(listener: DatabaseConnectionListener): () => void;
+    /**
+     * Removes a connection listener.
+     */
+    off(listener: DatabaseConnectionListener): boolean;
+    /**
+     * Removes all connection listeners.
+     */
+    removeAllListeners(): void;
+    /**
+     * Starts periodic database health checks. A tick is skipped while a
+     * previous check is still in flight, so a hung database never
+     * accumulates pending probes.
+     */
+    startHealthChecks(): void;
+    /**
+     * Stops periodic database health checks.
+     */
+    stopHealthChecks(): void;
+    /**
+     * Runs one scheduled health check immediately (also used by the timer).
+     * Resolves once the check, and any reconnect it triggers, has settled.
+     */
+    runScheduledHealthCheck(): Promise<void>;
+    /**
+     * Releases connection manager resources.
+     */
+    destroy(): Promise<void>;
+    private performScheduledHealthCheck;
+    private reconnectWithBackoff;
+    private performReconnect;
+    private emit;
+}
+/**
+ * Creates a database connection manager.
+ */
+export declare function createConnectionManager(options?: DatabaseConnectionManagerOptions): DatabaseConnectionManager;
+//# sourceMappingURL=databaseConnection.manager.d.ts.map