@zudojs/database 0.1.0 → 1.1.0

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

@@ -2,41 +2,198 @@
  * @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 type { DatabaseClient as DatabaseClientContract, DatabaseConnectionOptions, DatabaseHealth, DatabaseLogger, DatabaseStatus, TransactionCallback, TransactionOptions } from "../databaseType/databaseType.type.js";
-export type PrismaClientLike = PrismaClient;
-export interface DatabaseClientOptions extends DatabaseConnectionOptions {
-    readonly logger?: DatabaseLogger;
+import type { Prisma } from "@prisma/client";
+import { DatabaseError } from "@zudojs/errors";
+import type { DatabaseClient as DatabaseClientContract, DatabaseConnectionOptions, DatabaseHealth, DatabaseLogger, DatabaseOperationOptions, DatabaseStatus, TransactionCallback, TransactionIsolationLevel, TransactionOptions } from "../databaseType/databaseType.type.js";
+/**
+ * Transaction client handed to callbacks. This is Prisma's interactive
+ * transaction client (model delegates plus raw query helpers).
+ */
+export type DatabaseTransactionContext = Prisma.TransactionClient;
+/**
+ * Isolation levels accepted by Prisma's interactive transactions. The
+ * values are identical to the string names, so no namespace lookup is
+ * required.
+ */
+export declare const SUPPORTED_ISOLATION_LEVELS: readonly TransactionIsolationLevel[];
+/**
+ * Options forwarded to Prisma's interactive `$transaction`.
+ */
+export interface PrismaTransactionOptions {
+    readonly maxWait?: number;
+    readonly timeout?: number;
+    readonly isolationLevel?: TransactionIsolationLevel;
+}
+/**
+ * Structural view of the Prisma client surface this package relies on.
+ *
+ * Any generated `PrismaClient` satisfies it; tests can supply a stub.
+ */
+export interface PrismaClientLike {
+    $connect(): Promise<void>;
+    $disconnect(): Promise<void>;
+    $transaction<TResult>(callback: (transaction: DatabaseTransactionContext) => Promise<TResult>, options?: PrismaTransactionOptions): Promise<TResult>;
+    $queryRawUnsafe<TResult = unknown>(query: string, ...values: unknown[]): Promise<TResult>;
+    $executeRawUnsafe(query: string, ...values: unknown[]): Promise<number>;
+    $on?(event: "query", callback: (event: PrismaQueryEvent) => void): void;
+}
+/**
+ * Prisma query log event.
+ */
+export interface PrismaQueryEvent {
+    readonly query: string;
+    readonly params: string;
+    readonly duration: number;
+    readonly target: string;
+}
+/**
+ * Prisma driver adapter (for example `@prisma/adapter-pg`).
+ *
+ * Typed structurally so this package does not depend on any adapter.
+ */
+export interface PrismaDriverAdapterLike {
+    readonly provider: string;
+    readonly adapterName: string;
+}
+/**
+ * Options accepted by {@link DatabaseClient}.
+ *
+ * Prisma 7 requires either a driver adapter or an already constructed
+ * client; connection URLs, pool sizes and SSL flags are configured on the
+ * adapter and are therefore not accepted here.
+ */
+export interface DatabaseClientOptions extends Pick<DatabaseConnectionOptions, "connectionTimeoutMs" | "logging"> {
+    /**
+     * Pre-built Prisma client. Takes precedence over `adapter`.
+     */
     readonly prisma?: PrismaClientLike;
+    /**
+     * Prisma driver adapter used to construct a client when `prisma` is
+     * not supplied.
+     */
+    readonly adapter?: PrismaDriverAdapterLike;
+    readonly logger?: DatabaseLogger;
 }
-export type DatabaseTransactionContext = Prisma.TransactionClient;
-/** Prisma-backed database client. */
+/**
+ * Raw query options.
+ */
+export type RawQueryOptions = DatabaseOperationOptions;
+/**
+ * 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 declare class DatabaseClient implements DatabaseClientContract<DatabaseTransactionContext> {
     private readonly prisma;
     private readonly logger;
     private readonly options;
     private status;
     private connectedAt?;
+    private connectPromise?;
+    private disconnectPromise?;
     constructor(options?: DatabaseClientOptions);
+    /**
+     * Returns the underlying Prisma client.
+     */
     getPrisma(): PrismaClientLike;
+    /**
+     * Opens the connection. Concurrent calls share one in-flight attempt.
+     */
     connect(): Promise<void>;
+    private performConnect;
+    /**
+     * Closes the connection. Waits for an in-flight connect first.
+     */
     disconnect(): Promise<void>;
-    ping(): Promise<void>;
+    private performDisconnect;
+    /**
+     * Executes a lightweight `SELECT 1`.
+     */
+    ping(options?: RawQueryOptions): Promise<void>;
     getStatus(): DatabaseStatus;
     getConnectedAt(): Date | undefined;
-    healthCheck(): Promise<DatabaseHealth>;
+    /**
+     * Pings the database and reports the real lifecycle status.
+     */
+    healthCheck(options?: RawQueryOptions): Promise<DatabaseHealth>;
+    /**
+     * Runs a callback inside a Prisma interactive transaction.
+     *
+     * When `options.signal` aborts, the abort is raised *inside* the
+     * transaction callback so Prisma rolls the transaction back; the caller
+     * is released at the same moment. Racing only the outer promise let the
+     * callback finish and the transaction commit after the caller had
+     * already been told it was aborted.
+     */
     transaction<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
-    executeRaw(query: Prisma.Sql): Promise<number>;
-    queryRaw<TResult = unknown>(query: Prisma.Sql): Promise<TResult>;
+    /**
+     * Executes a raw statement with positional parameters and returns the
+     * affected row count.
+     */
+    executeRawUnsafe(sql: string, values?: readonly unknown[], options?: RawQueryOptions): Promise<number>;
+    /**
+     * Executes a raw query with positional parameters.
+     */
+    queryRawUnsafe<TResult = unknown>(sql: string, values?: readonly unknown[], options?: RawQueryOptions): Promise<TResult>;
+    /**
+     * Executes a `Prisma.sql` tagged statement.
+     *
+     * Only available when the underlying client supports `$executeRaw`.
+     */
+    executeRaw(query: Prisma.Sql, options?: RawQueryOptions): Promise<number>;
+    /**
+     * Executes a `Prisma.sql` tagged query.
+     */
+    queryRaw<TResult = unknown>(query: Prisma.Sql, options?: RawQueryOptions): Promise<TResult>;
     ensureConnected(): Promise<void>;
     destroy(): Promise<void>;
     private registerQueryLogging;
-    private buildTransactionOptions;
-    private mapIsolationLevel;
+    /**
+     * 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.
+     */
+    private runRaw;
     private withTimeout;
-    private normalizeError;
 }
+/**
+ * Maps package transaction options onto Prisma's interactive transaction
+ * options. Isolation levels are validated against the supported list and
+ * passed through as strings.
+ */
+export declare function buildPrismaTransactionOptions(options?: TransactionOptions): PrismaTransactionOptions;
+/**
+ * Throws an abort-typed `DatabaseError` when the signal is already aborted.
+ */
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+/**
+ * Error raised when an operation is cancelled through an `AbortSignal`.
+ */
+export declare class DatabaseAbortError extends DatabaseError {
+    constructor(signal?: AbortSignal);
+}
+/**
+ * Creates the error used when an operation is aborted through a signal.
+ */
+export declare function createAbortError(signal?: AbortSignal): DatabaseAbortError;
+/**
+ * Rejects as soon as the signal aborts, even if the operation is still
+ * running. The abort listener is removed once the operation settles.
+ */
+export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
 /** Creates a database client. */
 export declare function createDatabaseClient(options?: DatabaseClientOptions): DatabaseClient;
 //# sourceMappingURL=databaseClient.core.d.ts.map