@zudojs/database 1.3.2 → 1.5.0

package/dist/index.d.ts

@@ -18,19 +18,18 @@
  */
 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, getPrismaCodeMapping, 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, type PrismaCodeMapping, } 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";
+export { BaseRepository, mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, type RepositoryDelegate, type RepositoryDelegateOperations, type BaseRepositoryOptions, type SoftDeleteOptions, type CreateCursorOptions, type CursorQueryOptions, type TransactionClientLike, type RepositoryOperation, type RepositoryErrorContext, } from "./repository/index.js";
 export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, getTransactionContextFromError, isTransactionActive, isTransactionCommitted, isTransactionFailed, type TransactionStatus, type TransactionContext, type TransactionOutcome, type TransactionRetryOptions, type ManagedTransactionOptions, } from "./transaction/index.js";
 export { DatabaseUnitOfWork, createUnitOfWork, executeUnitOfWork, type UnitOfWork, type UnitOfWorkOptions, } from "./unitOfWork/index.js";
 export { QueryBuilder, createQueryBuilder, toPrismaWhere, toPrismaArgs, toPrismaOrderBy, toPrismaSelect, toPrismaSkipTake, type QueryCondition, type QueryFilter, type QueryOperator, type RelationOperator, type QueryBuilderState, type PrismaWhere, type PrismaQueryArgs, type ToPrismaArgsOptions, } from "./queryBuilder/index.js";
 export { equals, notEquals, inList, notInList, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, contains, startsWith, endsWith, isNull, isNotNull, and, or, not, condition, allOf, anyOf, fromObject, dateRange, oneOf, noneOf, optionalEquals, optionalContains, hasConditions, flattenAnd, cloneFilter, between, matchesPattern, isEmpty, isNotEmpty, dateOnly, isBefore, isAfter, isBetween, notCondition, relational, } from "./queryBuilder/index.js";
-export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, createInvalidCursorError, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, type CursorPayload, type EncodeCursorOptions, type DecodeCursorOptions, type KeysetPageOptions, type KeysetWhere, type KeysetDirection, type InvalidCursorReason, } from "./pagination/index.js";
+export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, createInvalidCursorError, isDateCursorValue, keysetStrictFilter, keysetTieFilter, nextMillisecond, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, type CursorPayload, type EncodeCursorOptions, type DecodeCursorOptions, type KeysetPageOptions, type KeysetWhere, type KeysetDirection, type InvalidCursorReason, } from "./pagination/index.js";
 export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, type RelationDefinition, type RelationType, type RelationLoadOptions, type RelationInclude, type ToPrismaIncludeOptions, } from "./relations/index.js";
 export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, normalizeAdvisoryKeyPair, resolveLockTransactionOptions, type DatabaseLockMode, type DatabaseLockOptions, type DatabaseLockResult, } from "./locks/index.js";
 export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, escapeCachePart, serializeCachePart, getOrSet, invalidateByPrefix, CACHE_KEY_SEPARATOR, type CacheEntry, type CacheOptions, type MemoryCacheOptions, type CacheStats, type DatabaseCache, } from "./cache/index.js";
 export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, SQL_IDENTIFIER_PATTERN, validateIdentifier, validateLockKey, quoteIdentifier, hashLockKey, fnv1a64, getSqlDialect, isSqlDialectName, UnsupportedDialectError, DEFAULT_SQL_DIALECT, type Migration, type MigrationRecord, type MigrationResult, type MigrationStatus, type MigrationRunnerOptions, type RunnerTransactionOptions, type SqlDialect, type SqlDialectName, } from "./migration/index.js";
 export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, type Seed, type SeedRecord, type SeedResult, type SeedStatus, type SeedRunnerOptions, } from "./seed/index.js";
 export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, getHealthCheckCause, DatabaseUnhealthyError, DEFAULT_HEALTH_TIMEOUT_MS, type DatabaseHealthStatus, type DatabaseHealth, type DatabaseHealthOptions, type DatabaseReadiness, } from "./health/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -18,7 +18,7 @@
  */
 export { noopDatabaseLogger } from "./databaseType/index.js";
 // Client
-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, } from "./databaseClient/index.js";
+export { DatabaseClient, DatabaseAbortError, createDatabaseClient, buildPrismaTransactionOptions, createAbortError, raceAbort, throwIfAborted, SUPPORTED_ISOLATION_LEVELS, normalizeDatabaseError, withDatabaseErrorMetadata, isPrismaError, isRetryableTransactionError, isConflictError, isNotFoundError, getPrismaCodeMapping, getDatabaseErrorCode, getDatabaseErrorKind, isDatabaseErrorLike, isNonDatabaseBaseError, toDatabaseErrorInfo, RETRYABLE_DATABASE_CODES, } from "./databaseClient/index.js";
 // Connection
 export { DatabaseConnectionManager, createConnectionManager, } from "./databaseConnection/index.js";
 // Database facade
@@ -33,7 +33,7 @@ export { DatabaseUnitOfWork, createUnitOfWork, executeUnitOfWork, } from "./unit
 export { QueryBuilder, createQueryBuilder, toPrismaWhere, toPrismaArgs, toPrismaOrderBy, toPrismaSelect, toPrismaSkipTake, } from "./queryBuilder/index.js";
 export { equals, notEquals, inList, notInList, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, contains, startsWith, endsWith, isNull, isNotNull, and, or, not, condition, allOf, anyOf, fromObject, dateRange, oneOf, noneOf, optionalEquals, optionalContains, hasConditions, flattenAnd, cloneFilter, between, matchesPattern, isEmpty, isNotEmpty, dateOnly, isBefore, isAfter, isBetween, notCondition, relational, } from "./queryBuilder/index.js";
 // Pagination
-export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, createInvalidCursorError, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination/index.js";
+export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, createInvalidCursorError, isDateCursorValue, keysetStrictFilter, keysetTieFilter, nextMillisecond, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination/index.js";
 // Relations
 export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, } from "./relations/index.js";
 // Locks
@@ -46,4 +46,3 @@ export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMi
 export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, } from "./seed/index.js";
 // Health
 export { checkDatabaseHealth, checkDatabaseReadiness, assertDatabaseHealth, isDatabaseHealthy, getHealthCheckCause, DatabaseUnhealthyError, DEFAULT_HEALTH_TIMEOUT_MS, } from "./health/index.js";
-//# sourceMappingURL=index.js.map

package/dist/locks/index.d.ts

@@ -4,4 +4,3 @@
  * Advisory and row-level database locking (PostgreSQL).
  */
 export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, normalizeAdvisoryKeyPair, resolveLockTransactionOptions, type DatabaseLockMode, type DatabaseLockOptions, type DatabaseLockResult, } from "./locks.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/locks/index.js

@@ -4,4 +4,3 @@
  * Advisory and row-level database locking (PostgreSQL).
  */
 export { DatabaseLockManager, createLockManager, acquireAdvisoryLock, lockRow, buildLockClause, normalizeAdvisoryKey, normalizeAdvisoryKeyPair, resolveLockTransactionOptions, } from "./locks.core.js";
-//# sourceMappingURL=index.js.map

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.
  *
@@ -129,4 +131,3 @@ export declare function normalizeAdvisoryKeyPair(namespace: string, lockKey: str
  * than `timeoutMs`.
  */
 export declare function resolveLockTransactionOptions(options?: DatabaseLockOptions): TransactionOptions | undefined;
-//# sourceMappingURL=locks.core.d.ts.map

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;
@@ -266,4 +268,3 @@ function validateId(id) {
         throw new TypeError("A database identifier must be a string or number.");
     }
 }
-//# sourceMappingURL=locks.core.js.map

package/dist/migration/index.d.ts

@@ -6,4 +6,3 @@
 export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, type Migration, type MigrationRecord, type MigrationResult, type MigrationStatus, type MigrationRunnerOptions, type RunnerTransactionOptions, } from "./migration.runner.js";
 export { SQL_IDENTIFIER_PATTERN, validateIdentifier, validateLockKey, quoteIdentifier, hashLockKey, fnv1a64, FNV1A_64_OFFSET_BASIS, FNV1A_64_PRIME, } from "./migration.helpers.js";
 export { getSqlDialect, isSqlDialectName, UnsupportedDialectError, DEFAULT_SQL_DIALECT, type SqlDialect, type SqlDialectName, } from "./migration.dialect.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/migration/index.js

@@ -6,4 +6,3 @@
 export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, } from "./migration.runner.js";
 export { SQL_IDENTIFIER_PATTERN, validateIdentifier, validateLockKey, quoteIdentifier, hashLockKey, fnv1a64, FNV1A_64_OFFSET_BASIS, FNV1A_64_PRIME, } from "./migration.helpers.js";
 export { getSqlDialect, isSqlDialectName, UnsupportedDialectError, DEFAULT_SQL_DIALECT, } from "./migration.dialect.js";
-//# sourceMappingURL=index.js.map

package/dist/migration/migration.dialect.d.ts

@@ -62,4 +62,3 @@ export declare function isSqlDialectName(value: unknown): value is SqlDialectNam
  * @throws {TypeError} for unknown dialect names.
  */
 export declare function getSqlDialect(name?: SqlDialectName): SqlDialect;
-//# sourceMappingURL=migration.dialect.d.ts.map

package/dist/migration/migration.dialect.js

@@ -60,4 +60,3 @@ export function getSqlDialect(name = DEFAULT_SQL_DIALECT) {
     }
     throw new TypeError(`Unknown SQL dialect: "${String(name)}".`);
 }
-//# sourceMappingURL=migration.dialect.js.map

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.
  */
@@ -62,4 +63,3 @@ export declare function fnv1a64(value: string): bigint;
  * Suitable as the single `bigint` argument of `pg_advisory_xact_lock`.
  */
 export declare function hashLockKey(value: string): bigint;
-//# sourceMappingURL=migration.helpers.d.ts.map

package/dist/migration/migration.helpers.js

@@ -58,6 +58,10 @@ export function validateMigration(migration) {
     if (migration.down !== undefined && typeof migration.down !== "function") {
         throw new TypeError(`Migration "${migration.name}" has an invalid down function.`);
     }
+    if (migration.transaction !== undefined &&
+        typeof migration.transaction !== "boolean") {
+        throw new TypeError(`Migration "${migration.name}" has an invalid transaction flag.`);
+    }
 }
 /**
  * Returns the highest registered migration version.
@@ -138,4 +142,3 @@ export function fnv1a64(value) {
 export function hashLockKey(value) {
     return BigInt.asIntN(64, fnv1a64(value));
 }
-//# sourceMappingURL=migration.helpers.js.map

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,15 +17,23 @@ 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.
      */
     migrate(): Promise<MigrationResult>;
+    /**
+     * Applies a `transaction: false` migration: the applied check and the
+     * history record run in short transactions under the advisory lock, the
+     * body runs on the root client outside any transaction.
+     */
+    private applyDetached;
+    /** The root Prisma client, handed to migrations that opt out of a transaction. */
+    private rootClient;
     /**
      * Alias of {@link migrate}.
      */
@@ -58,7 +66,11 @@ export declare class MigrationRunner {
      */
     getHistory(): Promise<readonly MigrationRecord[]>;
     private rollbackSteps;
+    /** Reverts a `transaction: false` migration; see {@link applyDetached}. */
+    private revertDetached;
     private revertRecord;
+    private requireRollback;
+    private runDown;
     private computePending;
     private buildTransactionOptions;
     private executor;
@@ -71,5 +83,4 @@ export declare class MigrationRunner {
 /**
  * Creates a migration runner.
  */
-export declare function createMigrationRunner(client: DatabaseClient, migrations: readonly Migration[], options?: MigrationRunnerOptions): MigrationRunner;
-//# sourceMappingURL=migration.runner.d.ts.map
+export declare function createMigrationRunner<TTransaction extends DatabaseTransactionContext = DatabaseTransactionContext>(client: DatabaseClient<TTransaction>, migrations: readonly Migration<TTransaction>[], options?: MigrationRunnerOptions): MigrationRunner<TTransaction>;

package/dist/migration/migration.runner.js

@@ -31,6 +31,10 @@ export class MigrationRunner {
         this.perItemTransaction = options.perItemTransaction ?? true;
         validateIdentifier(this.tableName, "migration table name");
         validateLockKey(this.lockKey, "migration lock key");
+        const detached = this.migrations.find((m) => m.transaction === false);
+        if (detached && !this.perItemTransaction) {
+            throw this.migrationError(`Migration "${detached.name}" sets transaction: false, which requires perItemTransaction: true.`, { metadata: { version: detached.version, name: detached.name } });
+        }
     }
     /**
      * Returns the migration status without executing anything.
@@ -69,16 +73,18 @@ export class MigrationRunner {
             return { applied: newlyApplied, skipped };
         }
         for (const migration of pending) {
-            const outcome = await this.client.transaction(async (transaction) => {
-                await this.acquireMigrationLock(transaction);
-                const applied = await this.getAppliedMigrations(transaction);
-                const existing = applied.find((r) => r.version === migration.version);
-                if (existing)
-                    return { record: existing, skipped: true };
-                await this.executeMigration(transaction, migration);
-                const record = await this.recordMigration(transaction, migration);
-                return { record, skipped: false };
-            }, this.buildTransactionOptions());
+            const outcome = migration.transaction === false
+                ? await this.applyDetached(migration)
+                : await this.client.transaction(async (transaction) => {
+                    await this.acquireMigrationLock(transaction);
+                    const applied = await this.getAppliedMigrations(transaction);
+                    const existing = applied.find((r) => r.version === migration.version);
+                    if (existing)
+                        return { record: existing, skipped: true };
+                    await this.executeMigration(transaction, migration);
+                    const record = await this.recordMigration(transaction, migration);
+                    return { record, skipped: false };
+                }, this.buildTransactionOptions());
             if (outcome.skipped)
                 skipped.push(outcome.record);
             else
@@ -86,6 +92,32 @@ export class MigrationRunner {
         }
         return { applied: newlyApplied, skipped };
     }
+    /**
+     * Applies a `transaction: false` migration: the applied check and the
+     * history record run in short transactions under the advisory lock, the
+     * body runs on the root client outside any transaction.
+     */
+    async applyDetached(migration) {
+        const existing = await this.client.transaction(async (transaction) => {
+            await this.acquireMigrationLock(transaction);
+            const applied = await this.getAppliedMigrations(transaction);
+            return applied.find((r) => r.version === migration.version);
+        }, this.buildTransactionOptions());
+        if (existing)
+            return { record: existing, skipped: true };
+        await this.executeMigration(this.rootClient(), migration);
+        const record = await this.client.transaction(async (transaction) => {
+            await this.acquireMigrationLock(transaction);
+            const applied = await this.getAppliedMigrations(transaction);
+            return (applied.find((r) => r.version === migration.version) ??
+                (await this.recordMigration(transaction, migration)));
+        }, this.buildTransactionOptions());
+        return { record, skipped: false };
+    }
+    /** The root Prisma client, handed to migrations that opt out of a transaction. */
+    rootClient() {
+        return this.client.getPrisma();
+    }
     /**
      * Alias of {@link migrate}.
      */
@@ -175,22 +207,41 @@ export class MigrationRunner {
             return rolledBack;
         }
         while (rolledBack.length < limit) {
-            const record = await this.client.transaction(async (transaction) => {
+            const step = await this.client.transaction(async (transaction) => {
                 await this.acquireMigrationLock(transaction);
                 const applied = await this.getAppliedMigrations(transaction);
                 const latest = applied[applied.length - 1];
                 if (!latest)
                     return null;
-                await this.revertRecord(transaction, latest);
-                return latest;
+                const migration = this.requireRollback(latest);
+                if (migration.transaction === false) {
+                    return { record: latest, detached: true };
+                }
+                await this.runDown(transaction, migration);
+                await this.deleteMigrationRecord(transaction, latest.version);
+                return { record: latest, detached: false };
             }, this.buildTransactionOptions());
-            if (!record)
+            if (!step)
                 break;
-            rolledBack.push(record);
+            if (step.detached)
+                await this.revertDetached(step.record);
+            rolledBack.push(step.record);
         }
         return rolledBack;
     }
+    /** Reverts a `transaction: false` migration; see {@link applyDetached}. */
+    async revertDetached(record) {
+        await this.runDown(this.rootClient(), this.requireRollback(record));
+        await this.client.transaction(async (transaction) => {
+            await this.acquireMigrationLock(transaction);
+            await this.deleteMigrationRecord(transaction, record.version);
+        }, this.buildTransactionOptions());
+    }
     async revertRecord(transaction, record) {
+        await this.runDown(transaction, this.requireRollback(record));
+        await this.deleteMigrationRecord(transaction, record.version);
+    }
+    requireRollback(record) {
         const migration = this.migrations.find((m) => m.version === record.version);
         if (!migration) {
             throw this.migrationError(`Migration "${record.name}" is recorded as applied but is not registered.`, { metadata: { version: record.version } });
@@ -198,6 +249,9 @@ export class MigrationRunner {
         if (!migration.down) {
             throw this.migrationError(`Migration "${migration.name}" does not define a rollback operation.`, { metadata: { version: migration.version } });
         }
+        return migration;
+    }
+    async runDown(transaction, migration) {
         try {
             await migration.down(transaction);
         }
@@ -207,7 +261,6 @@ export class MigrationRunner {
                 metadata: { version: migration.version, name: migration.name },
             });
         }
-        await this.deleteMigrationRecord(transaction, migration.version);
     }
     computePending(applied) {
         const versions = new Set(applied.map((record) => record.version));
@@ -294,4 +347,3 @@ function hasVersion(records, version) {
 export function createMigrationRunner(client, migrations, options) {
     return new MigrationRunner(client, migrations, options);
 }
-//# sourceMappingURL=migration.runner.js.map

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

@@ -7,18 +7,33 @@ 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>;
+    /**
+     * When `false`, `up` and `down` run outside a transaction, on the root
+     * client, which is what statements such as `CREATE INDEX CONCURRENTLY`
+     * or `ALTER TYPE ... ADD VALUE` require. Defaults to `true`.
+     *
+     * The applied check and the history record still happen inside short
+     * transactions under the advisory lock, but the lock is released while
+     * the body runs, so make such a migration idempotent (`IF NOT EXISTS`)
+     * to tolerate a second runner started at the same moment. Requires
+     * `perItemTransaction` (the default); a batch runner refuses it.
+     */
+    readonly transaction?: boolean;
 }
 /**
  * Persisted migration record.
@@ -38,10 +53,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[];
 }
 /**
@@ -82,4 +97,3 @@ export interface MigrationRunnerOptions {
      */
     readonly perItemTransaction?: boolean;
 }
-//# sourceMappingURL=migration.types.d.ts.map

package/dist/migration/migration.types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=migration.types.js.map

package/dist/pagination/index.d.ts

@@ -7,4 +7,4 @@ export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, ca
 export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, type KeysetPageOptions, type KeysetWhere, } from "./pagination.keyset.js";
 export { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, type KeysetDirection, } from "./pagination.keysetDirection.js";
 export { createInvalidCursorError, type InvalidCursorReason, } from "./pagination.cursorError.js";
-//# sourceMappingURL=index.d.ts.map
+export { isDateCursorValue, keysetStrictFilter, keysetTieFilter, nextMillisecond, } from "./pagination.keysetValue.js";

package/dist/pagination/index.js

@@ -7,4 +7,4 @@ export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, ca
 export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, } from "./pagination.keyset.js";
 export { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, } from "./pagination.keysetDirection.js";
 export { createInvalidCursorError, } from "./pagination.cursorError.js";
-//# sourceMappingURL=index.js.map
+export { isDateCursorValue, keysetStrictFilter, keysetTieFilter, nextMillisecond, } from "./pagination.keysetValue.js";

package/dist/pagination/pagination.core.d.ts

@@ -164,4 +164,3 @@ export declare function decodeCursor<T = unknown>(cursor: string, options?: Deco
  * restricted to the allowed fields.
  */
 export declare function validateCursorPayload(value: unknown, allowedFields: readonly string[]): asserts value is CursorPayload;
-//# sourceMappingURL=pagination.core.d.ts.map

package/dist/pagination/pagination.core.js

@@ -279,4 +279,3 @@ function validateSecret(secret) {
         throw new TypeError("A cursor secret must be a non-empty string.");
     }
 }
-//# sourceMappingURL=pagination.core.js.map

package/dist/pagination/pagination.cursorError.d.ts

@@ -14,4 +14,3 @@ export type InvalidCursorReason = "cursor_required" | "cursor_signature" | "curs
  * failure is kept only as the non-exposed `cause`.
  */
 export declare function createInvalidCursorError(message: string, reason: InvalidCursorReason, cause?: unknown): ValidationError;
-//# sourceMappingURL=pagination.cursorError.d.ts.map

package/dist/pagination/pagination.cursorError.js

@@ -14,4 +14,3 @@ export function createInvalidCursorError(message, reason, cause) {
         ...(cause !== undefined ? { cause } : {}),
     });
 }
-//# sourceMappingURL=pagination.cursorError.js.map

package/dist/pagination/pagination.keyset.d.ts

@@ -49,11 +49,23 @@ export declare function decodeKeysetCursor<TField extends string = string>(curso
  *
  * For a sort of `[a asc, b desc]` the forward result is
  * `OR: [{ a: { gt: A } }, { AND: [{ a: A }, { b: { lt: B } }] }]`.
+ *
+ * A value encoded from a `Date` is compared as its millisecond bucket
+ * (`gte C, lt C + 1ms` for a tie; `lt C` / `gte C + 1ms` for the strict
+ * part), so rows created in the same millisecond as the cursor row on a
+ * microsecond-precision column fall through to the next sort field
+ * instead of being skipped. See `pagination.keysetValue.ts`.
  */
 export declare function buildKeysetWhere<TField extends string = string>(cursor: CursorPayload, sort: readonly SortInput<TField>[]): KeysetWhere;
 /**
  * Derives the cursor payload for a row from the sort fields. A
  * `"backward"` cursor selects the rows before `row` instead of after it.
+ *
+ * `sort` must be the exact sort the page is fetched and decoded with.
+ * `BaseRepository#paginateCursor` appends the id field as a tiebreaker, so
+ * a cursor for a repository page must include it: use
+ * `repository.createCursor(row, { sort })`, which does, rather than this
+ * helper with the bare sort.
  */
 export declare function createKeysetCursor<TField extends string = string>(row: Readonly<Record<string, unknown>>, sort: readonly SortInput<TField>[], secret?: string, direction?: KeysetDirection): string;
 /**
@@ -69,4 +81,3 @@ export declare function createKeysetCursor<TField extends string = string>(row:
  * non-empty page, and `previousCursor` only when more rows precede it.
  */
 export declare function createKeysetPage<TEntity extends Readonly<Record<string, unknown>>, TField extends string = string>(rows: readonly TEntity[], options: KeysetPageOptions<TField>): CursorPaginatedResult<TEntity>;
-//# sourceMappingURL=pagination.keyset.d.ts.map

package/dist/pagination/pagination.keyset.js

@@ -1,6 +1,7 @@
 import { createCursorPaginatedResult, decodeCursor, encodeCursor, normalizeLimit, } from "./pagination.core.js";
 import { createInvalidCursorError } from "./pagination.cursorError.js";
 import { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, } from "./pagination.keysetDirection.js";
+import { keysetStrictFilter, keysetTieFilter } from "./pagination.keysetValue.js";
 /**
  * Decodes and validates a keyset cursor against the sort definition.
  *
@@ -32,6 +33,12 @@ export function decodeKeysetCursor(cursor, sort, secret) {
  *
  * For a sort of `[a asc, b desc]` the forward result is
  * `OR: [{ a: { gt: A } }, { AND: [{ a: A }, { b: { lt: B } }] }]`.
+ *
+ * A value encoded from a `Date` is compared as its millisecond bucket
+ * (`gte C, lt C + 1ms` for a tie; `lt C` / `gte C + 1ms` for the strict
+ * part), so rows created in the same millisecond as the cursor row on a
+ * microsecond-precision column fall through to the next sort field
+ * instead of being skipped. See `pagination.keysetValue.ts`.
  */
 export function buildKeysetWhere(cursor, sort) {
     validateSort(sort);
@@ -42,10 +49,10 @@ export function buildKeysetWhere(cursor, sort) {
         const conditions = effective
             .slice(0, index)
             .map((previous) => ({
-            [previous.field]: { equals: cursor[previous.field] },
+            [previous.field]: keysetTieFilter(cursor[previous.field]),
         }));
         conditions.push({
-            [entry.field]: { [comparison]: cursor[entry.field] },
+            [entry.field]: keysetStrictFilter(cursor[entry.field], comparison),
         });
         branches.push(conditions.length === 1 ? conditions[0] : { AND: conditions });
     });
@@ -54,6 +61,12 @@ export function buildKeysetWhere(cursor, sort) {
 /**
  * Derives the cursor payload for a row from the sort fields. A
  * `"backward"` cursor selects the rows before `row` instead of after it.
+ *
+ * `sort` must be the exact sort the page is fetched and decoded with.
+ * `BaseRepository#paginateCursor` appends the id field as a tiebreaker, so
+ * a cursor for a repository page must include it: use
+ * `repository.createCursor(row, { sort })`, which does, rather than this
+ * helper with the bare sort.
  */
 export function createKeysetCursor(row, sort, secret, direction = "forward") {
     validateSort(sort);
@@ -133,4 +146,3 @@ function validateSort(sort) {
         seen.add(entry.field);
     }
 }
-//# sourceMappingURL=pagination.keyset.js.map

package/dist/pagination/pagination.keysetDirection.d.ts

@@ -26,4 +26,3 @@ export declare function reverseKeysetSort<TField extends string>(sort: readonly
  * the requested sort going forward, the reversed sort going backward.
  */
 export declare function keysetFetchSort<TField extends string>(sort: readonly SortInput<TField>[], direction: KeysetDirection): readonly SortInput<TField>[];
-//# sourceMappingURL=pagination.keysetDirection.d.ts.map

package/dist/pagination/pagination.keysetDirection.js

@@ -27,4 +27,3 @@ export function reverseKeysetSort(sort) {
 export function keysetFetchSort(sort, direction) {
     return direction === "backward" ? reverseKeysetSort(sort) : sort;
 }
-//# sourceMappingURL=pagination.keysetDirection.js.map