@zudojs/database 0.1.0 → 1.0.0

package/dist/databaseClient/databaseClient.core.js

@@ -2,56 +2,113 @@
  * @zudojs/database — Database Client Core
  *
  * Prisma-backed database client implementation.
+ *
+ * The client is a thin lifecycle wrapper over a Prisma client. It never
+ * reads runtime values from the generated `Prisma` namespace, so it works
+ * whether the consumer's generated client lives in `@prisma/client` or in a
+ * custom output directory (the Prisma 7 default).
+ *
+ * Only PostgreSQL is exercised by the runners, locks and health helpers in
+ * this package.
  */
-import { PrismaClient, Prisma } from "@prisma/client";
-import { DatabaseError } from "@zudojs/errors";
+import { PrismaClient } from "@prisma/client";
+import { DatabaseError, DatabaseOperation } from "@zudojs/errors";
 import { createDefaultLogger } from "./databaseClient.logger.js";
-/** Prisma-backed database client. */
+import { 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
+ * required.
+ */
+export const SUPPORTED_ISOLATION_LEVELS = Object.freeze([
+    "ReadUncommitted",
+    "ReadCommitted",
+    "RepeatableRead",
+    "Serializable",
+]);
+/**
+ * Prisma-backed database client.
+ *
+ * `connect()` de-duplicates concurrent calls through a shared in-flight
+ * promise, and `disconnect()` waits for an in-flight connect before
+ * tearing the client down.
+ */
 export class DatabaseClient {
     prisma;
     logger;
     options;
     status = "disconnected";
     connectedAt;
+    connectPromise;
+    disconnectPromise;
     constructor(options = {}) {
         this.options = options;
         this.logger = options.logger ?? createDefaultLogger();
-        this.prisma =
-            options.prisma ??
-                new PrismaClient({
-                    log: options.logging
-                        ? [
-                            { emit: "event", level: "query" },
-                            { emit: "stdout", level: "error" },
-                            { emit: "stdout", level: "warn" },
-                        ]
-                        : [{ emit: "stdout", level: "error" }],
-                });
+        this.prisma = options.prisma ?? createPrismaClient(options);
         this.registerQueryLogging();
     }
+    /**
+     * Returns the underlying Prisma client.
+     */
     getPrisma() {
         return this.prisma;
     }
-    async connect() {
-        if (this.status === "connected" || this.status === "connecting")
-            return;
+    /**
+     * Opens the connection. Concurrent calls share one in-flight attempt.
+     */
+    connect() {
+        if (this.status === "connected")
+            return Promise.resolve();
+        if (this.connectPromise)
+            return this.connectPromise;
+        if (this.disconnectPromise) {
+            return this.disconnectPromise.then(() => this.connect());
+        }
         this.status = "connecting";
+        this.connectPromise = this.performConnect().finally(() => {
+            this.connectPromise = undefined;
+        });
+        return this.connectPromise;
+    }
+    async performConnect() {
         try {
             await this.withTimeout(this.prisma.$connect(), this.options.connectionTimeoutMs ?? 10_000, "Database connection timed out.");
+            if (this.status !== "connecting") {
+                // A disconnect raced this connect; leave its final state alone.
+                return;
+            }
             this.status = "connected";
             this.connectedAt = new Date();
             this.logger.info("Database connected.");
         }
         catch (error) {
             this.status = "error";
-            const normalized = this.normalizeError(error, "Database connection failed.");
+            const normalized = normalizeDatabaseError(error, {
+                operation: DatabaseOperation.CONNECT,
+                fallbackMessage: "Database connection failed.",
+            });
             this.logger.error(normalized.message, normalized);
             throw normalized;
         }
     }
-    async disconnect() {
-        if (this.status === "disconnected")
-            return;
+    /**
+     * Closes the connection. Waits for an in-flight connect first.
+     */
+    disconnect() {
+        if (this.disconnectPromise)
+            return this.disconnectPromise;
+        if (this.status === "disconnected" && !this.connectPromise) {
+            return Promise.resolve();
+        }
+        this.disconnectPromise = this.performDisconnect().finally(() => {
+            this.disconnectPromise = undefined;
+        });
+        return this.disconnectPromise;
+    }
+    async performDisconnect() {
+        if (this.connectPromise) {
+            await this.connectPromise.catch(() => undefined);
+        }
         this.status = "disconnecting";
         try {
             await this.prisma.$disconnect();
@@ -61,18 +118,27 @@ export class DatabaseClient {
         }
         catch (error) {
             this.status = "error";
-            const normalized = this.normalizeError(error, "Database disconnection failed.");
+            const normalized = normalizeDatabaseError(error, {
+                operation: DatabaseOperation.DISCONNECT,
+                fallbackMessage: "Database disconnection failed.",
+            });
             this.logger.error(normalized.message, normalized);
             throw normalized;
         }
     }
-    async ping() {
+    /**
+     * Executes a lightweight `SELECT 1`.
+     */
+    async ping(options = {}) {
         try {
-            await this.prisma.$queryRaw `SELECT 1`;
+            await this.runRaw(() => this.prisma.$queryRawUnsafe("SELECT 1"), options, "Database ping timed out.");
         }
         catch (error) {
             this.status = "error";
-            throw this.normalizeError(error, "Database ping failed.");
+            throw normalizeDatabaseError(error, {
+                operation: DatabaseOperation.QUERY,
+                fallbackMessage: "Database ping failed.",
+            });
         }
     }
     getStatus() {
@@ -81,18 +147,23 @@ export class DatabaseClient {
     getConnectedAt() {
         return this.connectedAt;
     }
-    async healthCheck() {
+    /**
+     * Pings the database and reports the real lifecycle status.
+     */
+    async healthCheck(options = {}) {
         const startedAt = Date.now();
         try {
-            await this.ping();
+            await this.ping(options);
             return {
-                status: "connected",
+                status: this.status,
                 latencyMs: Date.now() - startedAt,
                 checkedAt: new Date(),
             };
         }
         catch (error) {
-            const normalized = this.normalizeError(error, "Database health check failed.");
+            const normalized = normalizeDatabaseError(error, {
+                fallbackMessage: "Database health check failed.",
+            });
             return {
                 status: "error",
                 latencyMs: Date.now() - startedAt,
@@ -101,36 +172,102 @@ export class DatabaseClient {
             };
         }
     }
+    /**
+     * Runs a callback inside a Prisma interactive transaction.
+     */
     async transaction(callback, options = {}) {
-        if (typeof callback !== "function")
+        if (typeof callback !== "function") {
             throw new TypeError("A transaction callback is required.");
+        }
+        throwIfAborted(options.signal);
         await this.ensureConnected();
-        const transactionOptions = this.buildTransactionOptions(options);
+        const transactionOptions = buildPrismaTransactionOptions(options);
         try {
-            return await this.prisma.$transaction(async (transaction) => callback(transaction), transactionOptions);
+            return await raceAbort(this.prisma.$transaction(async (transaction) => callback(transaction), transactionOptions), options.signal);
         }
         catch (error) {
-            const normalized = this.normalizeError(error, "Database transaction failed.");
+            const normalized = normalizeDatabaseError(error, {
+                operation: DatabaseOperation.TRANSACTION,
+                fallbackMessage: "Database transaction failed.",
+                metadata: options.metadata,
+            });
             this.logger.error(normalized.message, normalized);
             throw normalized;
         }
     }
-    async executeRaw(query) {
+    /**
+     * Executes a raw statement with positional parameters and returns the
+     * affected row count.
+     */
+    async executeRawUnsafe(sql, values = [], options = {}) {
+        validateSql(sql);
+        await this.ensureConnected();
+        try {
+            return await this.runRaw(() => this.prisma.$executeRawUnsafe(sql, ...values), options, "Raw database execution timed out.");
+        }
+        catch (error) {
+            throw normalizeDatabaseError(error, {
+                operation: DatabaseOperation.QUERY,
+                fallbackMessage: "Raw database execution failed.",
+                metadata: options.metadata,
+            });
+        }
+    }
+    /**
+     * Executes a raw query with positional parameters.
+     */
+    async queryRawUnsafe(sql, values = [], options = {}) {
+        validateSql(sql);
         await this.ensureConnected();
         try {
-            return await this.prisma.$executeRaw(query);
+            return await this.runRaw(() => this.prisma.$queryRawUnsafe(sql, ...values), options, "Raw database query timed out.");
         }
         catch (error) {
-            throw this.normalizeError(error, "Raw database execution failed.");
+            throw normalizeDatabaseError(error, {
+                operation: DatabaseOperation.QUERY,
+                fallbackMessage: "Raw database query failed.",
+                metadata: options.metadata,
+            });
         }
     }
-    async queryRaw(query) {
+    /**
+     * Executes a `Prisma.sql` tagged statement.
+     *
+     * Only available when the underlying client supports `$executeRaw`.
+     */
+    async executeRaw(query, options = {}) {
+        const prisma = this.prisma;
+        if (typeof prisma.$executeRaw !== "function") {
+            throw new TypeError("The Prisma client does not support $executeRaw.");
+        }
         await this.ensureConnected();
         try {
-            return (await this.prisma.$queryRaw(query));
+            return await this.runRaw(() => prisma.$executeRaw(query), options, "Raw database execution timed out.");
         }
         catch (error) {
-            throw this.normalizeError(error, "Raw database query failed.");
+            throw normalizeDatabaseError(error, {
+                operation: DatabaseOperation.QUERY,
+                fallbackMessage: "Raw database execution failed.",
+            });
+        }
+    }
+    /**
+     * Executes a `Prisma.sql` tagged query.
+     */
+    async queryRaw(query, options = {}) {
+        const prisma = this.prisma;
+        if (typeof prisma.$queryRaw !== "function") {
+            throw new TypeError("The Prisma client does not support $queryRaw.");
+        }
+        await this.ensureConnected();
+        try {
+            return await this.runRaw(() => prisma.$queryRaw(query), options, "Raw database query timed out.");
+        }
+        catch (error) {
+            throw normalizeDatabaseError(error, {
+                operation: DatabaseOperation.QUERY,
+                fallbackMessage: "Raw database query failed.",
+            });
         }
     }
     async ensureConnected() {
@@ -143,58 +280,155 @@ export class DatabaseClient {
     registerQueryLogging() {
         if (!this.options.logging)
             return;
-        const prisma = this.prisma;
-        prisma.$on?.("query", (event) => {
+        this.prisma.$on?.("query", (event) => {
             this.logger.debug("Database query executed.", {
                 durationMs: event.duration,
                 target: event.target,
             });
         });
     }
-    buildTransactionOptions(options) {
-        return {
-            maxWait: options.maxWaitMs,
-            timeout: options.timeoutMs,
-            isolationLevel: options.isolationLevel
-                ? this.mapIsolationLevel(options.isolationLevel)
-                : undefined,
-        };
-    }
-    mapIsolationLevel(level) {
-        switch (level) {
-            case "ReadUncommitted":
-                return Prisma.TransactionIsolationLevel.ReadUncommitted;
-            case "ReadCommitted":
-                return Prisma.TransactionIsolationLevel.ReadCommitted;
-            case "RepeatableRead":
-                return Prisma.TransactionIsolationLevel.RepeatableRead;
-            case "Serializable":
-                return Prisma.TransactionIsolationLevel.Serializable;
-            default:
-                throw new TypeError(`Unsupported transaction isolation level: ${String(level)}`);
-        }
+    /**
+     * Applies `signal` and `timeoutMs` to a raw operation.
+     *
+     * Timeouts are client-side only: the caller stops waiting, but the
+     * statement keeps running on the server until it completes. Use
+     * `statement_timeout` for server-side cancellation.
+     */
+    runRaw(operation, options, timeoutMessage) {
+        throwIfAborted(options.signal);
+        const promise = raceAbort(operation(), options.signal);
+        return this.withTimeout(promise, options.timeoutMs ?? 0, timeoutMessage);
     }
     async withTimeout(promise, timeoutMs, message) {
-        if (timeoutMs <= 0)
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
             return promise;
         let timer;
         const timeout = new Promise((_, reject) => {
             timer = setTimeout(() => {
-                reject(new DatabaseError(message));
+                reject(new DatabaseError(message, {
+                    code: "ERR_DATABASE_TIMEOUT",
+                    statusCode: 503,
+                    metadata: { timeoutMs },
+                }));
             }, timeoutMs);
         });
         try {
             return await Promise.race([promise, timeout]);
         }
         finally {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
         }
     }
-    normalizeError(error, fallbackMessage) {
-        if (error instanceof DatabaseError)
-            return error;
-        return new DatabaseError(error instanceof Error ? error.message : fallbackMessage, { cause: error });
+}
+/**
+ * Builds a Prisma client from the supplied options.
+ *
+ * @throws {DatabaseError} when neither `prisma` nor `adapter` is provided.
+ */
+function createPrismaClient(options) {
+    if (!options.adapter) {
+        throw new DatabaseError("DatabaseClient requires either a pre-built `prisma` client or a Prisma driver `adapter` (for example @prisma/adapter-pg).", {
+            code: "ERR_DATABASE_CONNECTION",
+            operation: DatabaseOperation.CONNECT,
+            isOperational: false,
+        });
+    }
+    const log = options.logging
+        ? [
+            { emit: "event", level: "query" },
+            { emit: "stdout", level: "error" },
+            { emit: "stdout", level: "warn" },
+        ]
+        : [{ emit: "stdout", level: "error" }];
+    try {
+        const Constructor = PrismaClient;
+        return new Constructor({ adapter: options.adapter, log });
     }
+    catch (error) {
+        throw normalizeDatabaseError(error, {
+            operation: DatabaseOperation.CONNECT,
+            fallbackMessage: "Failed to construct the Prisma client.",
+        });
+    }
+}
+/**
+ * Maps package transaction options onto Prisma's interactive transaction
+ * options. Isolation levels are validated against the supported list and
+ * passed through as strings.
+ */
+export function buildPrismaTransactionOptions(options = {}) {
+    const result = {};
+    if (options.maxWaitMs !== undefined) {
+        validatePositive(options.maxWaitMs, "maxWaitMs");
+        result.maxWait = Math.floor(options.maxWaitMs);
+    }
+    if (options.timeoutMs !== undefined) {
+        validatePositive(options.timeoutMs, "timeoutMs");
+        result.timeout = Math.floor(options.timeoutMs);
+    }
+    if (options.isolationLevel !== undefined) {
+        if (!SUPPORTED_ISOLATION_LEVELS.includes(options.isolationLevel)) {
+            throw new TypeError(`Unsupported transaction isolation level: ${String(options.isolationLevel)}`);
+        }
+        result.isolationLevel = options.isolationLevel;
+    }
+    return result;
+}
+function validatePositive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new TypeError(`Transaction ${name} must be a positive finite number.`);
+    }
+}
+function validateSql(sql) {
+    if (typeof sql !== "string" || sql.trim().length === 0) {
+        throw new TypeError("A non-empty SQL string is required.");
+    }
+}
+/**
+ * Throws an abort-typed `DatabaseError` when the signal is already aborted.
+ */
+export function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw createAbortError(signal);
+}
+/**
+ * Error raised when an operation is cancelled through an `AbortSignal`.
+ */
+export class DatabaseAbortError extends DatabaseError {
+    constructor(signal) {
+        super("Database operation aborted.", {
+            code: "ERR_ABORTED",
+            statusCode: 499,
+            metadata: { aborted: true },
+            cause: signal?.reason,
+        });
+    }
+}
+/**
+ * Creates the error used when an operation is aborted through a signal.
+ */
+export function createAbortError(signal) {
+    return new DatabaseAbortError(signal);
+}
+/**
+ * Rejects as soon as the signal aborts, even if the operation is still
+ * running. The abort listener is removed once the operation settles.
+ */
+export function raceAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted) {
+        promise.catch(() => undefined);
+        return Promise.reject(createAbortError(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(createAbortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => {
+            signal.removeEventListener("abort", onAbort);
+        });
+    });
 }
 /** Creates a database client. */
 export function createDatabaseClient(options = {}) {

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

@@ -0,0 +1,112 @@
+/**
+ * @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, type DatabaseErrorOptions } from "@zudojs/errors";
+import type { DatabaseErrorInfo } from "../databaseType/databaseType.type.js";
+/**
+ * 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 declare function isDatabaseErrorLike(value: unknown): value is DatabaseError;
+/**
+ * Semantic outcome of a database failure.
+ */
+export type DatabaseErrorKind = "conflict" | "not-found" | "constraint" | "serialization" | "timeout" | "connection" | "validation" | "unknown";
+/**
+ * Options for {@link normalizeDatabaseError}.
+ */
+export interface NormalizeDatabaseErrorOptions {
+    /**
+     * Operation that failed. Used when the error does not already carry one.
+     */
+    readonly operation?: DatabaseOperation;
+    /**
+     * Message used when the underlying error has none, or when the underlying
+     * message must not be exposed (connection failures).
+     */
+    readonly fallbackMessage?: string;
+    /**
+     * Extra metadata merged into the normalised error.
+     */
+    readonly metadata?: DatabaseErrorOptions["metadata"];
+}
+/**
+ * Minimal structural view of a Prisma known-request / initialization error.
+ */
+export interface PrismaErrorLike {
+    readonly code?: string;
+    readonly errorCode?: string;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly clientVersion?: string;
+    readonly message?: string;
+    readonly retryable?: boolean;
+}
+/**
+ * Codes that indicate a transient transaction failure worth retrying.
+ */
+export declare const RETRYABLE_DATABASE_CODES: ReadonlySet<string>;
+/**
+ * Detects a Prisma error structurally.
+ */
+export declare function isPrismaError(value: unknown): value is PrismaErrorLike;
+/**
+ * Returns the Prisma / driver error code carried by an error, if any.
+ */
+export declare function getDatabaseErrorCode(error: unknown): string | undefined;
+/**
+ * Classifies a database error.
+ */
+export declare function getDatabaseErrorKind(error: unknown): DatabaseErrorKind;
+/**
+ * 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 declare function isRetryableTransactionError(error: unknown): boolean;
+/**
+ * Determines whether an error represents a unique-constraint conflict.
+ */
+export declare function isConflictError(error: unknown): boolean;
+/**
+ * Determines whether an error represents a missing record.
+ */
+export declare function isNotFoundError(error: unknown): boolean;
+/**
+ * Returns a copy of a `DatabaseError` with extra metadata, preserving
+ * `operation`, `driver` and `databaseCode` (which `BaseError.withMetadata`
+ * drops).
+ */
+export declare function withDatabaseErrorMetadata(error: DatabaseError, metadata: NonNullable<DatabaseErrorOptions["metadata"]>): DatabaseError;
+/**
+ * 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 declare function normalizeDatabaseError(error: unknown, options?: NormalizeDatabaseErrorOptions): DatabaseError;
+/**
+ * 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 declare function toDatabaseErrorInfo(error: unknown, options?: NormalizeDatabaseErrorOptions): DatabaseErrorInfo;
+//# sourceMappingURL=databaseClient.errors.d.ts.map