@zudojs/database 1.3.2 → 1.4.0

package/README.md

@@ -81,6 +81,42 @@ repository passes (`RepositoryDelegateOperations`).
 `adapter` (in which case it constructs the `PrismaClient` for you). It throws a
 `DatabaseError` if neither is supplied.
 
+### Typed transaction clients
+
+The transaction client handed to `transaction()` callbacks is inferred from the
+`prisma` instance you pass, so model delegates keep the types of your generated
+client. This works with Prisma 7's `prisma-client` generator (client generated
+into your application, e.g. `src/generated/prisma`) and with the legacy
+`prisma-client-js` generator alike; the package's published types never import
+`@prisma/client`, so they compile with `skipLibCheck: false`.
+
+```typescript
+import { PrismaClient } from "./generated/prisma/client.js";
+
+const client = createDatabaseClient({ prisma: new PrismaClient({ adapter }) });
+
+await client.transaction(async (tx) => {
+  await tx.user.create({ data: { email: "bob@example.com", name: "Bob" } }); // fully typed
+});
+```
+
+`withTransaction`, `withTransactionRetry`, `TransactionManager`,
+`DatabaseUnitOfWork`, the `Database` facade, the lock manager and the
+migration and seed runners all take the type from the client they wrap.
+
+When the concrete client type is unknown (`new DatabaseClient(options)`,
+`createDatabaseClient({ adapter })`, `getDatabase()`), callbacks receive
+`DatabaseTransactionContext`: the raw-query surface (`$queryRaw`,
+`$executeRaw`, `$queryRawUnsafe`, `$executeRawUnsafe`) without model
+delegates. Pass the client type to opt in, for example
+`createDatabaseClient<PrismaClient>({ adapter })`. `TransactionClientOf<typeof
+prisma>` names the inferred type if you need to annotate it.
+
+The adapter-only form constructs `PrismaClient` from `@prisma/client` at
+runtime, which only exists with the `prisma-client-js` generator. With the
+`prisma-client` generator, construct the client yourself and pass it as
+`prisma`.
+
 ## Querying
 
 ```typescript

package/dist/database/database.core.d.ts

@@ -1,4 +1,4 @@
-import { DatabaseClient, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike } from "../databaseClient/databaseClient.core.js";
+import { DatabaseClient, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike, type TransactionClientOf } from "../databaseClient/databaseClient.core.js";
 import type { DatabaseHealth, DatabaseStatus, TransactionCallback, TransactionOptions } from "../databaseType/databaseType.type.js";
 /**
  * Database facade used by the application layer.
@@ -6,14 +6,18 @@ import type { DatabaseHealth, DatabaseStatus, TransactionCallback, TransactionOp
  * This module provides a single database lifecycle entry point while
  * keeping the underlying Prisma client implementation inside the
  * database package.
+ *
+ * `TTransaction` is the transaction client handed to `transaction()`
+ * callbacks. {@link createDatabase} infers it from the wrapped client or
+ * from `options.prisma`.
  */
-export declare class Database {
+export declare class Database<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     private readonly client;
     /**
      * @param options Client options, or an existing {@link DatabaseClient}
      * to wrap so a single client is shared by the facade and other managers.
      */
-    constructor(options?: DatabaseClientOptions | DatabaseClient);
+    constructor(options?: DatabaseClientOptions | DatabaseClient<TTransaction>);
     /**
      * Initializes the database connection.
      */
@@ -41,14 +45,14 @@ export declare class Database {
     /**
      * Executes work inside a database transaction.
      */
-    transaction<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
+    transaction<TResult>(callback: TransactionCallback<TTransaction, TResult>, options?: TransactionOptions): Promise<TResult>;
     /**
      * Returns the underlying database client.
      *
      * This should primarily be used by repository and infrastructure
      * implementations that require direct Prisma access.
      */
-    getClient(): DatabaseClient;
+    getClient(): DatabaseClient<TTransaction>;
     /**
      * Returns the underlying Prisma client.
      */
@@ -59,7 +63,17 @@ export declare class Database {
     destroy(): Promise<void>;
 }
 /**
- * Creates a database facade.
+ * Creates a database facade over an existing client, keeping its
+ * transaction client type.
+ */
+export declare function createDatabase<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>): Database<TTransaction>;
+/**
+ * Creates a database facade from client options. The transaction client
+ * type is inferred from `options.prisma`.
+ */
+export declare function createDatabase<TClient extends PrismaClientLike = PrismaClientLike>(options?: DatabaseClientOptions<TClient>): Database<TransactionClientOf<TClient>>;
+/**
+ * Creates a database facade from client options or an existing client.
  */
 export declare function createDatabase(options?: DatabaseClientOptions | DatabaseClient): Database;
 /**

package/dist/database/database.core.js

@@ -1,10 +1,14 @@
-import { DatabaseClient, createDatabaseClient, } from "../databaseClient/databaseClient.core.js";
+import { DatabaseClient, } from "../databaseClient/databaseClient.core.js";
 /**
  * Database facade used by the application layer.
  *
  * This module provides a single database lifecycle entry point while
  * keeping the underlying Prisma client implementation inside the
  * database package.
+ *
+ * `TTransaction` is the transaction client handed to `transaction()`
+ * callbacks. {@link createDatabase} infers it from the wrapped client or
+ * from `options.prisma`.
  */
 export class Database {
     client;
@@ -14,7 +18,9 @@ export class Database {
      */
     constructor(options = {}) {
         this.client =
-            options instanceof DatabaseClient ? options : createDatabaseClient(options);
+            options instanceof DatabaseClient
+                ? options
+                : new DatabaseClient(options);
     }
     /**
      * Initializes the database connection.
@@ -80,9 +86,6 @@ export class Database {
         await this.client.destroy();
     }
 }
-/**
- * Creates a database facade.
- */
 export function createDatabase(options = {}) {
     return new Database(options);
 }

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

@@ -11,14 +11,10 @@
  * Only PostgreSQL is exercised by the runners, locks and health helpers in
  * this package.
  */
-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;
+import type { DatabaseTransactionContext, PrismaSqlLike, TransactionClientOf } from "./databaseClient.type.js";
+export type { DatabaseTransactionContext, PrismaSqlLike, TransactionClientOf, } from "./databaseClient.type.js";
 /**
  * Isolation levels accepted by Prisma's interactive transactions. The
  * values are identical to the string names, so no namespace lookup is
@@ -79,12 +75,15 @@ export interface PrismaDriverAdapterLike {
  * 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.
+ *
+ * `TClient` is the type of `prisma`; {@link createDatabaseClient} infers
+ * it to type the transaction client handed to callbacks.
  */
-export interface DatabaseClientOptions extends Pick<DatabaseConnectionOptions, "connectionTimeoutMs" | "logging"> {
+export interface DatabaseClientOptions<TClient extends PrismaClientLike = PrismaClientLike> extends Pick<DatabaseConnectionOptions, "connectionTimeoutMs" | "logging"> {
     /**
      * Pre-built Prisma client. Takes precedence over `adapter`.
      */
-    readonly prisma?: PrismaClientLike;
+    readonly prisma?: TClient;
     /**
      * Prisma driver adapter used to construct a client when `prisma` is
      * not supplied.
@@ -102,8 +101,15 @@ export type RawQueryOptions = DatabaseOperationOptions;
  * `connect()` de-duplicates concurrent calls through a shared in-flight
  * promise, and `disconnect()` waits for an in-flight connect before
  * tearing the client down.
+ *
+ * `TTransaction` is the client handed to `transaction()` callbacks.
+ * {@link createDatabaseClient} infers it from the Prisma client passed as
+ * `prisma`, so `tx.user.create(...)` is typed by the generated client. The
+ * constructor cannot infer it; `new DatabaseClient(options)` uses the
+ * structural {@link DatabaseTransactionContext} unless a type argument is
+ * given.
  */
-export declare class DatabaseClient implements DatabaseClientContract<DatabaseTransactionContext> {
+export declare class DatabaseClient<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> implements DatabaseClientContract<TTransaction> {
     private readonly prisma;
     private readonly logger;
     private readonly options;
@@ -151,7 +157,7 @@ export declare class DatabaseClient implements DatabaseClientContract<DatabaseTr
      * being logged as a database failure. Driver and database failures, and
      * any other thrown value, are normalised to a `DatabaseError` and logged.
      */
-    transaction<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
+    transaction<TResult>(callback: TransactionCallback<TTransaction, TResult>, options?: TransactionOptions): Promise<TResult>;
     /**
      * Executes a raw statement with positional parameters and returns the
      * affected row count.
@@ -166,11 +172,11 @@ export declare class DatabaseClient implements DatabaseClientContract<DatabaseTr
      *
      * Only available when the underlying client supports `$executeRaw`.
      */
-    executeRaw(query: Prisma.Sql, options?: RawQueryOptions): Promise<number>;
+    executeRaw(query: PrismaSqlLike, options?: RawQueryOptions): Promise<number>;
     /**
      * Executes a `Prisma.sql` tagged query.
      */
-    queryRaw<TResult = unknown>(query: Prisma.Sql, options?: RawQueryOptions): Promise<TResult>;
+    queryRaw<TResult = unknown>(query: PrismaSqlLike, options?: RawQueryOptions): Promise<TResult>;
     ensureConnected(): Promise<void>;
     destroy(): Promise<void>;
     private registerQueryLogging;
@@ -209,6 +215,16 @@ export declare function createAbortError(signal?: AbortSignal): DatabaseAbortErr
  * 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;
+/**
+ * Creates a database client.
+ *
+ * The transaction client handed to `transaction()` callbacks is inferred
+ * from `options.prisma`: with a generated client it is that client's own
+ * interactive transaction client, so model delegates are fully typed.
+ * Without `prisma` (adapter only) it is the structural
+ * {@link DatabaseTransactionContext}; pass the generated client type as a
+ * type argument (`createDatabaseClient<PrismaClient>({ adapter })`) to type
+ * the delegates.
+ */
+export declare function createDatabaseClient<TClient extends PrismaClientLike = PrismaClientLike>(options?: DatabaseClientOptions<TClient>): DatabaseClient<TransactionClientOf<TClient>>;
 //# sourceMappingURL=databaseClient.core.d.ts.map

package/dist/databaseClient/databaseClient.core.js

@@ -32,6 +32,13 @@ export const SUPPORTED_ISOLATION_LEVELS = Object.freeze([
  * `connect()` de-duplicates concurrent calls through a shared in-flight
  * promise, and `disconnect()` waits for an in-flight connect before
  * tearing the client down.
+ *
+ * `TTransaction` is the client handed to `transaction()` callbacks.
+ * {@link createDatabaseClient} infers it from the Prisma client passed as
+ * `prisma`, so `tx.user.create(...)` is typed by the generated client. The
+ * constructor cannot infer it; `new DatabaseClient(options)` uses the
+ * structural {@link DatabaseTransactionContext} unless a type argument is
+ * given.
  */
 export class DatabaseClient {
     prisma;
@@ -358,7 +365,7 @@ let cachedPrismaClientConstructor;
 function resolvePrismaClientConstructor() {
     if (cachedPrismaClientConstructor)
         return cachedPrismaClientConstructor;
-    const guidance = "Install it and run `prisma generate`, or pass an already-constructed client as `prisma` in the DatabaseClient options.";
+    const guidance = "Install it and run `prisma generate`, or pass an already-constructed client as `prisma` in the DatabaseClient options (required with the `prisma-client` generator, whose client is generated into your application rather than into @prisma/client).";
     let module;
     try {
         module = requirePeer("@prisma/client");
@@ -489,7 +496,17 @@ export function raceAbort(promise, signal) {
         });
     });
 }
-/** Creates a database client. */
+/**
+ * Creates a database client.
+ *
+ * The transaction client handed to `transaction()` callbacks is inferred
+ * from `options.prisma`: with a generated client it is that client's own
+ * interactive transaction client, so model delegates are fully typed.
+ * Without `prisma` (adapter only) it is the structural
+ * {@link DatabaseTransactionContext}; pass the generated client type as a
+ * type argument (`createDatabaseClient<PrismaClient>({ adapter })`) to type
+ * the delegates.
+ */
 export function createDatabaseClient(options = {}) {
     return new DatabaseClient(options);
 }

package/dist/databaseClient/databaseClient.type.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @zudojs/database — Database Client Types
+ *
+ * Transaction-client types owned by this package. They are structural on
+ * purpose: nothing here imports `@prisma/client`, so the published
+ * declarations resolve whether the consumer's generated client lives in
+ * `node_modules/.prisma/client` (`prisma-client-js`) or in an application
+ * directory such as `src/generated/prisma` (`prisma-client`, the Prisma 7
+ * default).
+ */
+/**
+ * A `Prisma.sql` tagged query. Any `Prisma.Sql` instance satisfies it.
+ */
+export interface PrismaSqlLike {
+    readonly strings: readonly string[];
+    readonly values: readonly unknown[];
+    readonly sql: string;
+}
+/**
+ * The raw-query surface every Prisma interactive transaction client
+ * exposes. This is the transaction type used when the concrete client type
+ * is not known: the default type argument of `DatabaseClient`,
+ * `TransactionManager`, `DatabaseUnitOfWork` and the other transaction
+ * helpers, and the type the migration, seed and lock helpers require.
+ *
+ * `createDatabaseClient({ prisma })` infers the real transaction client
+ * (model delegates included) from the client passed in; see
+ * {@link TransactionClientOf}.
+ *
+ * Declared as a type alias rather than an interface so it keeps an
+ * implicit index signature and stays assignable to
+ * `BaseRepository#withTransaction`'s `TransactionClientLike`.
+ */
+export type DatabaseTransactionContext = {
+    $queryRawUnsafe<TResult = unknown>(query: string, ...values: unknown[]): Promise<TResult>;
+    $executeRawUnsafe(query: string, ...values: unknown[]): Promise<number>;
+    $queryRaw<TResult = unknown>(query: TemplateStringsArray | PrismaSqlLike, ...values: unknown[]): Promise<TResult>;
+    $executeRaw(query: TemplateStringsArray | PrismaSqlLike, ...values: unknown[]): Promise<number>;
+};
+/**
+ * The interactive-transaction callback parameter of a Prisma client: for a
+ * generated client this is its own `Omit<PrismaClient, ITXClientDenyList>`
+ * (or the extended equivalent after `$extends`), so model delegates such
+ * as `tx.user` keep their generated types.
+ *
+ * Falls back to {@link DatabaseTransactionContext} for clients whose
+ * transaction callback cannot be read (hand-written stubs,
+ * `PrismaClientLike` itself) or does not expose the raw-query surface.
+ */
+export type TransactionClientOf<TClient> = TClient extends {
+    $transaction(callback: (transaction: infer TTransaction) => never, ...rest: never[]): unknown;
+} ? [TTransaction] extends [never] ? DatabaseTransactionContext : [TTransaction] extends [DatabaseTransactionContext] ? TTransaction : DatabaseTransactionContext : DatabaseTransactionContext;
+//# sourceMappingURL=databaseClient.type.d.ts.map

package/dist/databaseClient/databaseClient.type.js

@@ -0,0 +1,12 @@
+/**
+ * @zudojs/database — Database Client Types
+ *
+ * Transaction-client types owned by this package. They are structural on
+ * purpose: nothing here imports `@prisma/client`, so the published
+ * declarations resolve whether the consumer's generated client lives in
+ * `node_modules/.prisma/client` (`prisma-client-js`) or in an application
+ * directory such as `src/generated/prisma` (`prisma-client`, the Prisma 7
+ * default).
+ */
+export {};
+//# sourceMappingURL=databaseClient.type.js.map

package/dist/databaseClient/index.d.ts

@@ -3,6 +3,6 @@
  *
  * Prisma-backed database client and connection infrastructure.
  */
-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 { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike, type PrismaDriverAdapterLike, type PrismaQueryEvent, type PrismaTransactionOptions, type PrismaSqlLike, type RawQueryOptions, type TransactionClientOf, } from "./databaseClient.core.js";
 export { normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, type DatabaseErrorKind, type NormalizeDatabaseErrorOptions, type PrismaErrorLike, } from "./databaseClient.errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  */
 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, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, 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 { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike, type PrismaDriverAdapterLike, type PrismaQueryEvent, type PrismaTransactionOptions, type PrismaSqlLike, type RawQueryOptions, type TransactionClientOf, 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, mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, type RepositoryDelegate, type RepositoryDelegateOperations, type BaseRepositoryOptions, type SoftDeleteOptions, type CursorQueryOptions, type TransactionClientLike, type RepositoryOperation, type RepositoryErrorContext, } from "./repository/index.js";

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

@@ -62,31 +62,33 @@ export interface DatabaseLockResult {
  * Application-level lock abstraction for PostgreSQL.
  *
  * Locks are acquired inside a transaction and released when it ends.
+ * `TTransaction` is the transaction client handed to callbacks, taken from
+ * the database client.
  */
-export declare class DatabaseLockManager {
+export declare class DatabaseLockManager<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     private readonly client;
-    constructor(client: DatabaseClient);
+    constructor(client: DatabaseClient<TTransaction>);
     /**
      * 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>;
+    withAdvisoryLock<TResult>(lockKey: string, callback: (transaction: TTransaction) => 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>;
+    withRowLock<TResult>(tableName: string, id: string | number, callback: (transaction: TTransaction) => Promise<TResult>, options?: DatabaseLockOptions): Promise<TResult>;
     /**
      * Returns the underlying database client.
      */
-    getClient(): DatabaseClient;
+    getClient(): DatabaseClient<TTransaction>;
 }
 /**
  * Creates a lock manager.
  */
-export declare function createLockManager(client: DatabaseClient): DatabaseLockManager;
+export declare function createLockManager<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>): DatabaseLockManager<TTransaction>;
 /**
  * Acquires a PostgreSQL advisory transaction lock.
  *

package/dist/locks/locks.core.js

@@ -5,6 +5,8 @@ import { fnv1a64, hashLockKey, SQL_IDENTIFIER_PATTERN, } from "../migration/migr
  * Application-level lock abstraction for PostgreSQL.
  *
  * Locks are acquired inside a transaction and released when it ends.
+ * `TTransaction` is the transaction client handed to callbacks, taken from
+ * the database client.
  */
 export class DatabaseLockManager {
     client;

package/dist/migration/migration.helpers.d.ts

@@ -1,3 +1,4 @@
+import type { DatabaseTransactionContext } from "../databaseClient/databaseClient.type.js";
 import type { Migration, MigrationRecord } from "./migration.types.js";
 /**
  * Default migration table.
@@ -14,15 +15,15 @@ export declare const SQL_IDENTIFIER_PATTERN: RegExp;
 /**
  * Normalizes and validates migrations.
  */
-export declare function normalizeMigrations(migrations: readonly Migration[]): readonly Migration[];
+export declare function normalizeMigrations<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(migrations: readonly Migration<TTransaction>[]): readonly Migration<TTransaction>[];
 /**
  * Validates one migration.
  */
-export declare function validateMigration(migration: Migration): void;
+export declare function validateMigration<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(migration: Migration<TTransaction>): void;
 /**
  * Returns the highest registered migration version.
  */
-export declare function getLatestVersion(migrations: readonly Migration[]): number;
+export declare function getLatestVersion(migrations: readonly Pick<Migration, "version">[]): number;
 /**
  * Returns the highest applied migration version.
  */

package/dist/migration/migration.runner.d.ts

@@ -9,7 +9,7 @@ export { DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, normalizeMigrations, g
  * lock before deciding what to execute, so two runners started together
  * never apply or revert the same migration twice.
  */
-export declare class MigrationRunner {
+export declare class MigrationRunner<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     private readonly client;
     private readonly migrations;
     private readonly tableName;
@@ -17,11 +17,11 @@ export declare class MigrationRunner {
     private readonly dialect;
     private readonly transactionOptions;
     private readonly perItemTransaction;
-    constructor(client: DatabaseClient, migrations: readonly Migration[], options?: MigrationRunnerOptions);
+    constructor(client: DatabaseClient<TTransaction>, migrations: readonly Migration<TTransaction>[], options?: MigrationRunnerOptions);
     /**
      * Returns the migration status without executing anything.
      */
-    status(): Promise<MigrationStatus>;
+    status(): Promise<MigrationStatus<TTransaction>>;
     /**
      * Applies every pending migration in version order.
      */
@@ -71,5 +71,5 @@ export declare class MigrationRunner {
 /**
  * Creates a migration runner.
  */
-export declare function createMigrationRunner(client: DatabaseClient, migrations: readonly Migration[], options?: MigrationRunnerOptions): MigrationRunner;
+export declare function createMigrationRunner<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>, migrations: readonly Migration<TTransaction>[], options?: MigrationRunnerOptions): MigrationRunner<TTransaction>;
 //# sourceMappingURL=migration.runner.d.ts.map

package/dist/migration/migration.types.d.ts

@@ -7,18 +7,21 @@ import type { SqlDialectName } from "./migration.dialect.js";
  * Each migration must have a unique, monotonically ordered version. The
  * version is stored in a BIGINT column, so timestamp-style versions such as
  * `20260908120000` are supported up to `Number.MAX_SAFE_INTEGER`.
+ *
+ * `TTransaction` is the transaction client handed to `up` and `down`;
+ * `createMigrationRunner` infers it from the database client.
  */
-export interface Migration {
+export interface Migration<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     readonly version: number;
     readonly name: string;
     /**
      * Applies the migration.
      */
-    readonly up: (database: DatabaseTransactionContext) => Promise<void>;
+    readonly up: (database: TTransaction) => Promise<void>;
     /**
      * Reverts the migration.
      */
-    readonly down?: (database: DatabaseTransactionContext) => Promise<void>;
+    readonly down?: (database: TTransaction) => Promise<void>;
 }
 /**
  * Persisted migration record.
@@ -38,10 +41,10 @@ export interface MigrationResult {
 /**
  * Migration status.
  */
-export interface MigrationStatus {
+export interface MigrationStatus<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     readonly currentVersion: number;
     readonly latestVersion: number;
-    readonly pending: readonly Migration[];
+    readonly pending: readonly Migration<TTransaction>[];
     readonly applied: readonly MigrationRecord[];
 }
 /**

package/dist/seed/seed.runner.d.ts

@@ -3,8 +3,11 @@ import { type SqlDialectName } from "../migration/migration.dialect.js";
 import type { RunnerTransactionOptions } from "../migration/migration.types.js";
 /**
  * Defines a database seed operation.
+ *
+ * `TTransaction` is the transaction client handed to `run` and `rollback`;
+ * {@link createSeedRunner} infers it from the database client.
  */
-export interface Seed {
+export interface Seed<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     /**
      * Unique seed name.
      */
@@ -16,11 +19,11 @@ export interface Seed {
     /**
      * Executes the seed.
      */
-    readonly run: (database: DatabaseTransactionContext) => Promise<void>;
+    readonly run: (database: TTransaction) => Promise<void>;
     /**
      * Optional cleanup operation.
      */
-    readonly rollback?: (database: DatabaseTransactionContext) => Promise<void>;
+    readonly rollback?: (database: TTransaction) => Promise<void>;
 }
 /**
  * Persisted seed execution record.
@@ -45,8 +48,8 @@ export interface SeedResult {
 /**
  * Seed runner status.
  */
-export interface SeedStatus {
-    readonly pending: readonly Seed[];
+export interface SeedStatus<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
+    readonly pending: readonly Seed<TTransaction>[];
     readonly applied: readonly SeedRecord[];
 }
 /**
@@ -91,7 +94,7 @@ export declare const DEFAULT_SEED_LOCK = "database:seeds";
  * lock before deciding what to execute, so two runners started together
  * never apply or revert the same seed twice.
  */
-export declare class SeedRunner {
+export declare class SeedRunner<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     private readonly client;
     private readonly seeds;
     private readonly tableName;
@@ -99,11 +102,11 @@ export declare class SeedRunner {
     private readonly dialect;
     private readonly transactionOptions;
     private readonly perItemTransaction;
-    constructor(client: DatabaseClient, seeds: readonly Seed[], options?: SeedRunnerOptions);
+    constructor(client: DatabaseClient<TTransaction>, seeds: readonly Seed<TTransaction>[], options?: SeedRunnerOptions);
     /**
      * Returns the seed runner status.
      */
-    status(): Promise<SeedStatus>;
+    status(): Promise<SeedStatus<TTransaction>>;
     /**
      * Executes every pending seed in order.
      */
@@ -148,13 +151,13 @@ export declare class SeedRunner {
 /**
  * Creates a seed runner.
  */
-export declare function createSeedRunner(client: DatabaseClient, seeds: readonly Seed[], options?: SeedRunnerOptions): SeedRunner;
+export declare function createSeedRunner<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>, seeds: readonly Seed<TTransaction>[], options?: SeedRunnerOptions): SeedRunner<TTransaction>;
 /**
  * Validates and sorts seed definitions (stable sort on `order`).
  */
-export declare function normalizeSeeds(seeds: readonly Seed[]): readonly Seed[];
+export declare function normalizeSeeds<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(seeds: readonly Seed<TTransaction>[]): readonly Seed<TTransaction>[];
 /**
  * Validates one seed definition.
  */
-export declare function validateSeed(seed: Seed): void;
+export declare function validateSeed<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(seed: Seed<TTransaction>): void;
 //# sourceMappingURL=seed.runner.d.ts.map

package/dist/transaction/transaction.core.d.ts

@@ -64,15 +64,18 @@ export interface TransactionRetryOptions extends ManagedTransactionOptions {
 export declare function createTransactionId(): string;
 /**
  * Manages transaction execution and lifecycle metadata.
+ *
+ * `TTransaction` is the transaction client handed to callbacks, taken from
+ * the {@link DatabaseClient} the manager wraps.
  */
-export declare class TransactionManager {
+export declare class TransactionManager<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
     private readonly client;
-    constructor(client: DatabaseClient);
+    constructor(client: DatabaseClient<TTransaction>);
     /**
      * Executes a callback inside a managed transaction and returns its
      * result.
      */
-    execute<TResult>(callback: (transaction: DatabaseTransactionContext, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TResult>;
+    execute<TResult>(callback: (transaction: TTransaction, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TResult>;
     /**
      * Executes a callback inside a managed transaction and returns the
      * result together with the final context (`status: "committed"`).
@@ -86,16 +89,16 @@ export declare class TransactionManager {
      * `NotFoundError` or `DomainError`) rolls the transaction back and is
      * rethrown as the same, unmodified instance.
      */
-    run<TResult>(callback: (transaction: DatabaseTransactionContext, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TransactionOutcome<TResult>>;
+    run<TResult>(callback: (transaction: TTransaction, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TransactionOutcome<TResult>>;
     /**
      * Returns the database client used by the manager.
      */
-    getClient(): DatabaseClient;
+    getClient(): DatabaseClient<TTransaction>;
 }
 /**
  * Creates a transaction manager.
  */
-export declare function createTransactionManager(client: DatabaseClient): TransactionManager;
+export declare function createTransactionManager<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>): TransactionManager<TTransaction>;
 /**
  * Executes a managed database transaction.
  *
@@ -104,7 +107,7 @@ export declare function createTransactionManager(client: DatabaseClient): Transa
  * validation, not-found, ...) propagates unchanged; driver and database
  * failures and any other thrown value become a `DatabaseError`.
  */
-export declare function withTransaction<TResult>(client: DatabaseClient, callback: (transaction: DatabaseTransactionContext, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TResult>;
+export declare function withTransaction<TResult, TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>, callback: (transaction: TTransaction, context: TransactionContext) => Promise<TResult>, options?: ManagedTransactionOptions): Promise<TResult>;
 /**
  * Executes a transaction with retry support.
  *
@@ -112,7 +115,7 @@ export declare function withTransaction<TResult>(client: DatabaseClient, callbac
  * callback must be idempotent with respect to any side effects performed
  * outside the transaction client (for example, sending emails).
  */
-export declare function withTransactionRetry<TResult>(client: DatabaseClient, callback: (transaction: DatabaseTransactionContext, context: TransactionContext) => Promise<TResult>, options?: TransactionRetryOptions): Promise<TResult>;
+export declare function withTransactionRetry<TResult, TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>, callback: (transaction: TTransaction, context: TransactionContext) => Promise<TResult>, options?: TransactionRetryOptions): Promise<TResult>;
 /**
  * Creates an immutable transaction context.
  */

package/dist/transaction/transaction.core.js

@@ -12,6 +12,9 @@ export function createTransactionId() {
 }
 /**
  * Manages transaction execution and lifecycle metadata.
+ *
+ * `TTransaction` is the transaction client handed to callbacks, taken from
+ * the {@link DatabaseClient} the manager wraps.
  */
 export class TransactionManager {
     client;

package/dist/unitOfWork/unitOfWork.core.d.ts

@@ -8,37 +8,39 @@ import type { TransactionCallback, TransactionOptions } from "../databaseType/da
  * Repositories must be rebound to the transaction client handed to the
  * callback (see `BaseRepository.withTransaction`); repositories built from
  * the root client run outside the transaction.
+ *
+ * `TTransaction` is the transaction client handed to the callback.
  */
-export interface UnitOfWork {
-    execute<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
+export interface UnitOfWork<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
+    execute<TResult>(callback: TransactionCallback<TTransaction, TResult>, options?: TransactionOptions): Promise<TResult>;
 }
 /**
  * Configuration for a unit of work.
  */
-export interface UnitOfWorkOptions {
-    readonly client: DatabaseClient;
+export interface UnitOfWorkOptions<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> {
+    readonly client: DatabaseClient<TTransaction>;
 }
 /**
  * Prisma-backed unit of work.
  */
-export declare class DatabaseUnitOfWork implements UnitOfWork {
+export declare class DatabaseUnitOfWork<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext> implements UnitOfWork<TTransaction> {
     private readonly client;
-    constructor(options: UnitOfWorkOptions);
+    constructor(options: UnitOfWorkOptions<TTransaction>);
     /**
      * Executes a callback inside a transaction.
      */
-    execute<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
+    execute<TResult>(callback: TransactionCallback<TTransaction, TResult>, options?: TransactionOptions): Promise<TResult>;
     /**
      * Returns the database client used by this unit of work.
      */
-    getClient(): DatabaseClient;
+    getClient(): DatabaseClient<TTransaction>;
 }
 /**
  * Creates a database unit of work.
  */
-export declare function createUnitOfWork(client: DatabaseClient): DatabaseUnitOfWork;
+export declare function createUnitOfWork<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>): DatabaseUnitOfWork<TTransaction>;
 /**
  * Executes a callback as a single database transaction.
  */
-export declare function executeUnitOfWork<TResult>(client: DatabaseClient, callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
+export declare function executeUnitOfWork<TResult, TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>, callback: TransactionCallback<TTransaction, TResult>, options?: TransactionOptions): Promise<TResult>;
 //# sourceMappingURL=unitOfWork.core.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/database",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Database abstraction layer with clients, repositories, transactions, and query building for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -41,8 +41,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.3.1",
-    "@zudojs/logger": "1.4.2",
+    "@zudojs/errors": "1.3.2",
+    "@zudojs/logger": "1.4.3",
     "@zudojs/types": "1.2.0"
   },
   "peerDependencies": {