@zudojs/database 0.0.1 → 1.0.0

package/dist/databaseConnection/databaseConnection.manager.js

@@ -1,5 +1,7 @@
-import { DatabaseError } from "@zudojs/errors";
+import { DatabaseOperation } from "@zudojs/errors";
 import { DatabaseClient, } from "../databaseClient/databaseClient.core.js";
+import { normalizeDatabaseError } from "../databaseClient/databaseClient.errors.js";
+import { checkDatabaseHealth, getHealthCheckCause, } from "../health/health.check.js";
 /**
  * Manages the database connection lifecycle.
  *
@@ -12,47 +14,68 @@ export class DatabaseConnectionManager {
     listeners = new Set();
     autoConnect;
     healthCheckIntervalMs;
+    healthCheckTimeoutMs;
+    reconnect;
     healthCheckTimer;
-    connectionPromise;
+    healthCheckInFlight;
+    consecutiveFailures = 0;
+    reconnectPromise;
+    lastHealth;
+    destroyed = false;
     constructor(options = {}) {
-        this.client = new DatabaseClient(options);
-        this.autoConnect = options.autoConnect ?? false;
-        this.healthCheckIntervalMs = options.healthCheckIntervalMs;
+        const { client, autoConnect, healthCheckIntervalMs, healthCheckTimeoutMs, reconnect, ...clientOptions } = options;
+        this.client = client ?? new DatabaseClient(clientOptions);
+        this.autoConnect = autoConnect ?? false;
+        if (healthCheckIntervalMs !== undefined) {
+            if (!Number.isFinite(healthCheckIntervalMs) || healthCheckIntervalMs <= 0) {
+                throw new TypeError("healthCheckIntervalMs must be a positive finite number.");
+            }
+            this.healthCheckIntervalMs = Math.floor(healthCheckIntervalMs);
+        }
+        const defaultTimeout = Math.min(this.healthCheckIntervalMs ?? 5_000, 5_000);
+        this.healthCheckTimeoutMs = healthCheckTimeoutMs ?? defaultTimeout;
+        if (!Number.isFinite(this.healthCheckTimeoutMs) || this.healthCheckTimeoutMs <= 0) {
+            throw new TypeError("healthCheckTimeoutMs must be a positive finite number.");
+        }
+        this.reconnect =
+            reconnect === false
+                ? undefined
+                : {
+                    failureThreshold: Math.max(1, Math.floor(reconnect?.failureThreshold ?? 1)),
+                    maxAttempts: Math.max(1, Math.floor(reconnect?.maxAttempts ?? 5)),
+                    baseDelayMs: Math.max(0, reconnect?.baseDelayMs ?? 500),
+                    maxDelayMs: Math.max(0, reconnect?.maxDelayMs ?? 30_000),
+                };
     }
     /**
      * Initializes the connection manager.
      */
     async initialize() {
-        if (!this.autoConnect) {
+        if (!this.autoConnect)
             return;
-        }
         await this.connect();
     }
     /**
-     * Opens the database connection.
+     * Opens the database connection. Concurrent calls share the client's
+     * in-flight attempt.
      */
     async connect() {
-        if (this.client.getStatus() === "connected") {
+        if (this.client.getStatus() === "connected")
             return;
-        }
-        if (this.connectionPromise) {
-            return this.connectionPromise;
-        }
         this.emit("connecting");
-        this.connectionPromise = this.client
-            .connect()
-            .then(() => {
+        try {
+            await this.client.connect();
+            this.consecutiveFailures = 0;
             this.emit("connected");
             this.startHealthChecks();
-        })
-            .catch((error) => {
+        }
+        catch (error) {
             this.emit("error", error);
-            throw this.normalizeError(error, "Database connection failed.");
-        })
-            .finally(() => {
-            this.connectionPromise = undefined;
-        });
-        return this.connectionPromise;
+            throw normalizeDatabaseError(error, {
+                operation: DatabaseOperation.CONNECT,
+                fallbackMessage: "Database connection failed.",
+            });
+        }
     }
     /**
      * Closes the database connection.
@@ -60,9 +83,8 @@ export class DatabaseConnectionManager {
     async disconnect() {
         this.stopHealthChecks();
         const status = this.client.getStatus();
-        if (status === "disconnected" || status === "disconnecting") {
+        if (status === "disconnected" || status === "disconnecting")
             return;
-        }
         this.emit("disconnecting");
         try {
             await this.client.disconnect();
@@ -70,7 +92,10 @@ export class DatabaseConnectionManager {
         }
         catch (error) {
             this.emit("error", error);
-            throw this.normalizeError(error, "Database disconnection failed.");
+            throw normalizeDatabaseError(error, {
+                operation: DatabaseOperation.DISCONNECT,
+                fallbackMessage: "Database disconnection failed.",
+            });
         }
     }
     /**
@@ -88,10 +113,16 @@ export class DatabaseConnectionManager {
         return this.client.getStatus();
     }
     /**
-     * Performs a database health check.
+     * Performs a database health check (with the configured timeout).
      */
     async healthCheck() {
-        return this.client.healthCheck();
+        return this.client.healthCheck({ timeoutMs: this.healthCheckTimeoutMs });
+    }
+    /**
+     * Returns the result of the most recent scheduled health check.
+     */
+    getLastHealth() {
+        return this.lastHealth;
     }
     /**
      * Returns the underlying database client.
@@ -124,92 +155,123 @@ export class DatabaseConnectionManager {
         this.listeners.clear();
     }
     /**
-     * Starts periodic database health checks.
+     * 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() {
         this.stopHealthChecks();
         const interval = this.healthCheckIntervalMs;
-        if (!interval || interval <= 0) {
+        if (!interval || this.destroyed)
             return;
-        }
         this.healthCheckTimer = setInterval(() => {
             void this.runScheduledHealthCheck();
         }, interval);
-        this.unrefTimer();
+        this.healthCheckTimer.unref?.();
     }
     /**
      * Stops periodic database health checks.
      */
     stopHealthChecks() {
-        if (!this.healthCheckTimer) {
+        if (!this.healthCheckTimer)
             return;
-        }
         clearInterval(this.healthCheckTimer);
         this.healthCheckTimer = undefined;
     }
+    /**
+     * Runs one scheduled health check immediately (also used by the timer).
+     * Resolves once the check, and any reconnect it triggers, has settled.
+     */
+    async runScheduledHealthCheck() {
+        if (this.healthCheckInFlight)
+            return this.healthCheckInFlight;
+        this.healthCheckInFlight = this.performScheduledHealthCheck().finally(() => {
+            this.healthCheckInFlight = undefined;
+        });
+        return this.healthCheckInFlight;
+    }
     /**
      * Releases connection manager resources.
      */
     async destroy() {
+        this.destroyed = true;
         this.stopHealthChecks();
         await this.disconnect();
         this.removeAllListeners();
     }
-    /**
-     * Emits a connection lifecycle event.
-     */
-    emit(event, error) {
+    async performScheduledHealthCheck() {
+        const health = await checkDatabaseHealth(this.client, {
+            timeoutMs: this.healthCheckTimeoutMs,
+        });
+        this.lastHealth = health;
+        if (health.healthy) {
+            this.consecutiveFailures = 0;
+            return;
+        }
+        this.consecutiveFailures += 1;
+        this.emit("error", getHealthCheckCause(health) ?? health.error);
+        if (this.reconnect &&
+            !this.destroyed &&
+            this.consecutiveFailures >= this.reconnect.failureThreshold) {
+            await this.reconnectWithBackoff();
+        }
+    }
+    reconnectWithBackoff() {
+        if (this.reconnectPromise)
+            return this.reconnectPromise;
+        this.reconnectPromise = this.performReconnect().finally(() => {
+            this.reconnectPromise = undefined;
+        });
+        return this.reconnectPromise;
+    }
+    async performReconnect() {
+        const policy = this.reconnect;
+        if (!policy)
+            return;
+        for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+            if (this.destroyed)
+                return;
+            this.emit("reconnecting", undefined, attempt);
+            try {
+                await this.client.disconnect().catch(() => undefined);
+                await this.client.connect();
+                this.consecutiveFailures = 0;
+                this.emit("connected", undefined, attempt);
+                return;
+            }
+            catch (error) {
+                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);
+            }
+        }
+    }
+    emit(event, error, attempt) {
         const details = Object.freeze({
             status: this.client.getStatus(),
             timestamp: new Date(),
             error,
+            attempt,
         });
         for (const listener of [...this.listeners]) {
             try {
                 listener(event, details);
             }
             catch {
-                // Connection lifecycle listeners must never break the
-                // database connection lifecycle itself.
-            }
-        }
-    }
-    /**
-     * Runs a scheduled health check.
-     */
-    async runScheduledHealthCheck() {
-        try {
-            const health = await this.healthCheck();
-            if (health.status === "error") {
-                this.emit("error", health.error);
+                // Listeners must never break the connection lifecycle itself.
             }
         }
-        catch (error) {
-            this.emit("error", error);
-        }
-    }
-    /**
-     * Prevents the health-check timer from keeping Node alive.
-     */
-    unrefTimer() {
-        const timer = this.healthCheckTimer;
-        timer?.unref?.();
-    }
-    /**
-     * Normalizes connection failures.
-     */
-    normalizeError(error, fallbackMessage) {
-        if (error instanceof DatabaseError) {
-            return error;
-        }
-        return new DatabaseError(error instanceof Error ? error.message : fallbackMessage, {
-            cause: error,
-            metadata: {
-                status: this.client.getStatus(),
-            },
-        });
     }
 }
+function sleep(milliseconds) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, milliseconds);
+        timer.unref?.();
+    });
+}
 /**
  * Creates a database connection manager.
  */

package/dist/databaseConnection/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Connection lifecycle management with health checks.
  */
-export { DatabaseConnectionManager, createConnectionManager, type DatabaseConnectionEvent, type DatabaseConnectionListener, type DatabaseConnectionEventDetails, type DatabaseConnectionManagerOptions, } from "./databaseConnection.manager.js";
+export { DatabaseConnectionManager, createConnectionManager, type DatabaseConnectionEvent, type DatabaseConnectionListener, type DatabaseConnectionEventDetails, type DatabaseConnectionManagerOptions, type DatabaseReconnectOptions, } from "./databaseConnection.manager.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/databaseType/databaseType.type.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Database connection lifecycle states.
+ */
+export type DatabaseStatus = "disconnected" | "connecting" | "connected" | "disconnecting" | "error";
+/**
+ * Supported transaction isolation levels.
+ */
+export type TransactionIsolationLevel = "ReadUncommitted" | "ReadCommitted" | "RepeatableRead" | "Serializable";
+/**
+ * Database operation types.
+ */
+export type DatabaseOperation = "create" | "read" | "update" | "delete" | "upsert" | "count" | "aggregate" | "transaction" | "raw";
+/**
+ * Options shared by database operations.
+ */
+export interface DatabaseOperationOptions {
+    /**
+     * Aborts the operation from the caller's side. The repository rejects
+     * with an `ERR_OPERATION_CANCELLED` DatabaseError as soon as the signal
+     * fires; the underlying database query is not cancelled server-side.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Client-side timeout in milliseconds. When exceeded the caller receives
+     * an `ERR_DATABASE_TIMEOUT` DatabaseError; the query itself keeps running
+     * on the server until it completes (use a statement timeout for real
+     * cancellation).
+     */
+    readonly timeoutMs?: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Options used when establishing a database connection.
+ *
+ * Prisma 7 configures the connection URL, pool size and SSL on the driver
+ * adapter, so only options this package can actually honour are declared
+ * here.
+ */
+export interface DatabaseConnectionOptions {
+    /**
+     * Client-side deadline for `$connect()` (default 10 000 ms). Non-finite
+     * or non-positive values disable the timeout.
+     */
+    readonly connectionTimeoutMs?: number;
+    /**
+     * Emits Prisma query events (duration and target only) to the logger.
+     */
+    readonly logging?: boolean;
+}
+/**
+ * Lifecycle-oriented health snapshot returned by `DatabaseClient.healthCheck()`
+ * and the `Database` facade. For the richer probe result (healthy /
+ * degraded / unhealthy plus an error object) use `checkDatabaseHealth`
+ * from the health module.
+ */
+export interface DatabaseClientHealth {
+    readonly status: DatabaseStatus;
+    readonly latencyMs?: number;
+    readonly checkedAt: Date;
+    readonly error?: string;
+}
+/**
+ * @deprecated Use {@link DatabaseClientHealth}. Kept as an alias so the
+ * name does not clash with the health module's `DatabaseHealth`.
+ */
+export type DatabaseHealth = DatabaseClientHealth;
+/**
+ * Transaction configuration.
+ */
+export interface TransactionOptions extends DatabaseOperationOptions {
+    readonly isolationLevel?: TransactionIsolationLevel;
+    readonly timeoutMs?: number;
+    readonly maxWaitMs?: number;
+}
+/**
+ * Generic transaction callback.
+ */
+export type TransactionCallback<TContext, TResult> = (context: TContext) => Promise<TResult>;
+/**
+ * Generic database client contract implemented by the concrete
+ * `DatabaseClient` class. Kept out of the root barrel to avoid clashing
+ * with the class name; prefer the {@link DatabaseClientContract} alias.
+ */
+export interface DatabaseClient<TTransactionContext = unknown> {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<void>;
+    getStatus(): DatabaseStatus;
+    healthCheck(): Promise<DatabaseClientHealth>;
+    transaction<TResult>(callback: TransactionCallback<TTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
+}
+/**
+ * Alias of the {@link DatabaseClient} contract interface.
+ */
+export type DatabaseClientContract<TTransactionContext = unknown> = DatabaseClient<TTransactionContext>;
+/**
+ * Generic repository contract.
+ */
+export interface Repository<TEntity, TId = string, TCreateInput = Partial<TEntity>, TUpdateInput = Partial<TEntity>, TFilter = unknown> {
+    findById(id: TId, options?: DatabaseOperationOptions): Promise<TEntity | null>;
+    findOne(filter: TFilter, options?: DatabaseOperationOptions): Promise<TEntity | null>;
+    findMany(filter?: TFilter, options?: DatabaseOperationOptions): Promise<readonly TEntity[]>;
+    findPaginated(filter?: TFilter, options?: QueryOptions): Promise<PaginatedResult<TEntity>>;
+    create(input: TCreateInput, options?: DatabaseOperationOptions): Promise<TEntity>;
+    createMany(inputs: readonly TCreateInput[], options?: DatabaseOperationOptions): Promise<number>;
+    update(id: TId, input: TUpdateInput, options?: DatabaseOperationOptions): Promise<TEntity>;
+    upsert(where: TFilter, create: TCreateInput, update: TUpdateInput, options?: DatabaseOperationOptions): Promise<TEntity>;
+    delete(id: TId, options?: DatabaseOperationOptions): Promise<void>;
+    deleteMany(filter: TFilter, options?: DatabaseOperationOptions): Promise<number>;
+    exists(filter: TFilter, options?: DatabaseOperationOptions): Promise<boolean>;
+    count(filter?: TFilter, options?: DatabaseOperationOptions): Promise<number>;
+}
+/**
+ * Repository contract for entities that support soft deletion.
+ */
+export interface SoftDeletableRepository<TEntity, TId = string, TCreateInput = Partial<TEntity>, TUpdateInput = Partial<TEntity>, TFilter = unknown> extends Repository<TEntity, TId, TCreateInput, TUpdateInput, TFilter> {
+    softDelete(id: TId, options?: DatabaseOperationOptions): Promise<TEntity>;
+    restore(id: TId, options?: DatabaseOperationOptions): Promise<TEntity>;
+    findDeleted(filter?: TFilter, options?: DatabaseOperationOptions): Promise<readonly TEntity[]>;
+}
+/**
+ * Pagination request.
+ */
+export interface PaginationInput {
+    readonly page?: number;
+    readonly limit?: number;
+}
+/**
+ * Pagination metadata.
+ */
+export interface PaginationMeta {
+    readonly page: number;
+    readonly limit: number;
+    readonly total: number;
+    readonly totalPages: number;
+    readonly hasNextPage: boolean;
+    readonly hasPreviousPage: boolean;
+    /** Alias of `hasNextPage`. */
+    readonly hasNext: boolean;
+    /** Alias of `hasPreviousPage`. */
+    readonly hasPrev: boolean;
+}
+/**
+ * Paginated repository result.
+ */
+export interface PaginatedResult<TEntity> {
+    readonly data: readonly TEntity[];
+    readonly meta: PaginationMeta;
+}
+/**
+ * Sorting direction.
+ */
+export type SortDirection = "asc" | "desc";
+/**
+ * Generic sort definition.
+ */
+export interface SortInput<TField extends string = string> {
+    readonly field: TField;
+    readonly direction: SortDirection;
+}
+/**
+ * Generic query options.
+ */
+export interface QueryOptions<TField extends string = string> extends DatabaseOperationOptions {
+    readonly pagination?: PaginationInput;
+    readonly sort?: readonly SortInput<TField>[];
+}
+/**
+ * Database entity base contract.
+ */
+export interface DatabaseEntity<TId = string> {
+    readonly id: TId;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+/**
+ * Soft-deletable entity contract.
+ */
+export interface SoftDeletableEntity extends DatabaseEntity {
+    readonly deletedAt: Date | null;
+}
+/**
+ * Auditable entity contract.
+ */
+export interface AuditableEntity extends DatabaseEntity {
+    readonly createdBy?: string;
+    readonly updatedBy?: string;
+}
+/**
+ * Plain, serialisable description of a database failure. Produced by
+ * `toDatabaseErrorInfo` in the client module.
+ */
+export interface DatabaseErrorInfo {
+    /**
+     * Prisma / driver code (for example `P2002`) when known, otherwise the
+     * `DatabaseError.code` (for example `ERR_DATABASE`).
+     */
+    readonly code?: string;
+    readonly message: string;
+    /**
+     * Operation that failed (a `DatabaseOperation` value from
+     * `@zudojs/errors`, or one of the local {@link DatabaseOperation} names).
+     */
+    readonly operation?: string;
+    readonly model?: string;
+    readonly field?: string;
+    readonly constraint?: string;
+    readonly cause?: unknown;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Database logger contract.
+ */
+export interface DatabaseLogger {
+    debug(message: string, metadata?: Readonly<Record<string, unknown>>): void;
+    info(message: string, metadata?: Readonly<Record<string, unknown>>): void;
+    warn(message: string, metadata?: Readonly<Record<string, unknown>>): void;
+    error(message: string, error?: unknown, metadata?: Readonly<Record<string, unknown>>): void;
+}
+/**
+ * Default no-op database logger.
+ */
+export declare const noopDatabaseLogger: DatabaseLogger;
+//# sourceMappingURL=databaseType.type.d.ts.map

package/dist/databaseType/databaseType.type.js

@@ -0,0 +1,10 @@
+/**
+ * Default no-op database logger.
+ */
+export const noopDatabaseLogger = Object.freeze({
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+});
+//# sourceMappingURL=databaseType.type.js.map

package/dist/health/health.check.d.ts

@@ -0,0 +1,74 @@
+import { DatabaseError } from "@zudojs/errors";
+import type { DatabaseClient } from "../databaseClient/databaseClient.core.js";
+/**
+ * Health status of the database.
+ */
+export type DatabaseHealthStatus = "healthy" | "unhealthy" | "degraded";
+/**
+ * Detailed database health information.
+ */
+export interface DatabaseHealth {
+    readonly status: DatabaseHealthStatus;
+    readonly healthy: boolean;
+    readonly latencyMs: number;
+    readonly checkedAt: Date;
+    readonly message?: string;
+    readonly error?: {
+        readonly name: string;
+        readonly message: string;
+        readonly code?: string;
+        readonly databaseCode?: string;
+    };
+}
+/**
+ * Database health check options.
+ */
+export interface DatabaseHealthOptions {
+    readonly timeoutMs?: number;
+}
+/**
+ * Result of a database readiness check.
+ */
+export interface DatabaseReadiness {
+    readonly ready: boolean;
+    readonly checkedAt: Date;
+    readonly latencyMs: number;
+    readonly message?: string;
+}
+/**
+ * Default database health-check timeout.
+ */
+export declare const DEFAULT_HEALTH_TIMEOUT_MS = 5000;
+/**
+ * Error raised by {@link assertDatabaseHealth}. The underlying failure is
+ * preserved as `cause`.
+ */
+export declare class DatabaseUnhealthyError extends DatabaseError {
+    readonly health: DatabaseHealth;
+    constructor(health: DatabaseHealth, cause: unknown);
+}
+/**
+ * Performs a lightweight database health check.
+ */
+export declare function checkDatabaseHealth(client: DatabaseClient, options?: DatabaseHealthOptions): Promise<DatabaseHealth>;
+/**
+ * Returns the original error that made a health check fail, if any.
+ */
+export declare function getHealthCheckCause(health: DatabaseHealth): unknown;
+/**
+ * Performs a database readiness check.
+ *
+ * Readiness is intentionally stricter than health. A degraded
+ * connection remains healthy but may still be considered ready.
+ */
+export declare function checkDatabaseReadiness(client: DatabaseClient, options?: DatabaseHealthOptions): Promise<DatabaseReadiness>;
+/**
+ * Throws a {@link DatabaseUnhealthyError} (with the real failure as
+ * `cause`) when the database is not healthy.
+ */
+export declare function assertDatabaseHealth(client: DatabaseClient, options?: DatabaseHealthOptions): Promise<DatabaseHealth>;
+/**
+ * Checks whether a database is reachable.
+ */
+export declare function isDatabaseHealthy(client: DatabaseClient, options?: DatabaseHealthOptions): Promise<boolean>;
+//# sourceMappingURL=health.check.d.ts.map