@zudojs/database 0.1.0 → 1.0.0

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

@@ -0,0 +1,75 @@
+import type { DatabaseClient, DatabaseTransactionContext } from "../databaseClient/databaseClient.core.js";
+import type { Migration, MigrationRecord, MigrationResult, MigrationRunnerOptions, MigrationStatus } from "./migration.types.js";
+export * from "./migration.types.js";
+export { DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, normalizeMigrations, getCurrentVersion, getLatestVersion, validateMigration, } from "./migration.helpers.js";
+/**
+ * Runs and tracks database migrations.
+ *
+ * Every entry point re-reads the applied history *inside* the advisory
+ * lock before deciding what to execute, so two runners started together
+ * never apply or revert the same migration twice.
+ */
+export declare class MigrationRunner {
+    private readonly client;
+    private readonly migrations;
+    private readonly tableName;
+    private readonly lockKey;
+    private readonly dialect;
+    private readonly transactionOptions;
+    private readonly perItemTransaction;
+    constructor(client: DatabaseClient, migrations: readonly Migration[], options?: MigrationRunnerOptions);
+    /**
+     * Returns the migration status without executing anything.
+     */
+    status(): Promise<MigrationStatus>;
+    /**
+     * Applies every pending migration in version order.
+     */
+    migrate(): Promise<MigrationResult>;
+    /**
+     * Alias of {@link migrate}.
+     */
+    run(): Promise<MigrationResult>;
+    /**
+     * Reverts the most recently applied migration.
+     *
+     * With a `steps` argument, reverts up to that many migrations (newest
+     * first) and returns the reverted records in rollback order.
+     */
+    rollback(): Promise<MigrationRecord | null>;
+    rollback(steps: number): Promise<readonly MigrationRecord[]>;
+    /**
+     * Reverts every applied migration, newest first.
+     */
+    rollbackAll(): Promise<readonly MigrationRecord[]>;
+    /**
+     * Creates the tracking table if it does not exist.
+     */
+    ensureMigrationTable(): Promise<void>;
+    /**
+     * Returns the applied migrations ordered by version.
+     *
+     * Pass the transaction context to read inside a running transaction
+     * (for example after acquiring the advisory lock).
+     */
+    getAppliedMigrations(transaction?: DatabaseTransactionContext): Promise<readonly MigrationRecord[]>;
+    /**
+     * Alias of {@link getAppliedMigrations}.
+     */
+    getHistory(): Promise<readonly MigrationRecord[]>;
+    private rollbackSteps;
+    private revertRecord;
+    private computePending;
+    private buildTransactionOptions;
+    private executor;
+    private executeMigration;
+    private recordMigration;
+    private deleteMigrationRecord;
+    private acquireMigrationLock;
+    private migrationError;
+}
+/**
+ * Creates a migration runner.
+ */
+export declare function createMigrationRunner(client: DatabaseClient, migrations: readonly Migration[], options?: MigrationRunnerOptions): MigrationRunner;
+//# sourceMappingURL=migration.runner.d.ts.map

package/dist/migration/migration.runner.js

@@ -1,16 +1,24 @@
-import { DatabaseError } from "@zudojs/errors";
-import { Prisma } from "@prisma/client";
-import { DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, normalizeMigrations, getCurrentVersion, getLatestVersion, quoteIdentifier, hashLockKey, } from "./migration.helpers.js";
+import { DatabaseError, DatabaseOperation, } from "@zudojs/errors";
+import { isDatabaseErrorLike } from "../databaseClient/databaseClient.errors.js";
+import { DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, normalizeMigrations, getCurrentVersion, getLatestVersion, hashLockKey, validateIdentifier, validateLockKey, } from "./migration.helpers.js";
+import { getSqlDialect } from "./migration.dialect.js";
 export * from "./migration.types.js";
 export { DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, normalizeMigrations, getCurrentVersion, getLatestVersion, validateMigration, } from "./migration.helpers.js";
 /**
  * Runs and tracks database migrations.
+ *
+ * Every entry point re-reads the applied history *inside* the advisory
+ * lock before deciding what to execute, so two runners started together
+ * never apply or revert the same migration twice.
  */
 export class MigrationRunner {
     client;
     migrations;
     tableName;
     lockKey;
+    dialect;
+    transactionOptions;
+    perItemTransaction;
     constructor(client, migrations, options = {}) {
         if (!client)
             throw new TypeError("A database client is required.");
@@ -18,122 +26,120 @@ export class MigrationRunner {
         this.migrations = normalizeMigrations(migrations);
         this.tableName = options.tableName ?? DEFAULT_MIGRATION_TABLE;
         this.lockKey = options.lockKey ?? DEFAULT_MIGRATION_LOCK;
-        this.validateTableName();
-    }
-    validateTableName() {
-        const validateIdentifier = (id, name) => {
-            if (typeof id !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(id)) {
-                throw new TypeError(`Invalid ${name}: "${id}".`);
-            }
-        };
+        this.dialect = getSqlDialect(options.dialect);
+        this.transactionOptions = { ...options.transaction };
+        this.perItemTransaction = options.perItemTransaction ?? true;
         validateIdentifier(this.tableName, "migration table name");
+        validateLockKey(this.lockKey, "migration lock key");
     }
+    /**
+     * Returns the migration status without executing anything.
+     */
     async status() {
         await this.ensureMigrationTable();
         const applied = await this.getAppliedMigrations();
-        const appliedVersions = new Set(applied.map((m) => m.version));
-        const pending = this.migrations.filter((m) => !appliedVersions.has(m.version));
         return {
             currentVersion: getCurrentVersion(applied),
             latestVersion: getLatestVersion(this.migrations),
-            pending,
+            pending: this.computePending(applied),
             applied,
         };
     }
+    /**
+     * Applies every pending migration in version order.
+     */
     async migrate() {
         await this.ensureMigrationTable();
-        const applied = await this.getAppliedMigrations();
-        const appliedVersions = new Set(applied.map((m) => m.version));
-        const pending = this.migrations.filter((m) => !appliedVersions.has(m.version));
+        const before = await this.getAppliedMigrations();
+        const pending = this.computePending(before);
         if (pending.length === 0)
-            return { applied: [], skipped: applied };
+            return { applied: [], skipped: before };
         const newlyApplied = [];
-        await this.client.transaction(async (transaction) => {
-            await this.acquireMigrationLock(transaction);
-            for (const migration of pending) {
+        const skipped = [...before];
+        if (!this.perItemTransaction) {
+            await this.client.transaction(async (transaction) => {
+                await this.acquireMigrationLock(transaction);
+                const applied = await this.getAppliedMigrations(transaction);
+                skipped.push(...applied.filter((r) => !hasVersion(before, r.version)));
+                for (const migration of this.computePending(applied)) {
+                    await this.executeMigration(transaction, migration);
+                    newlyApplied.push(await this.recordMigration(transaction, migration));
+                }
+            }, this.buildTransactionOptions());
+            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);
-                newlyApplied.push(record);
-            }
-        });
-        return { applied: newlyApplied, skipped: applied };
+                return { record, skipped: false };
+            }, this.buildTransactionOptions());
+            if (outcome.skipped)
+                skipped.push(outcome.record);
+            else
+                newlyApplied.push(outcome.record);
+        }
+        return { applied: newlyApplied, skipped };
     }
-    async rollback() {
-        await this.ensureMigrationTable();
-        const applied = await this.getAppliedMigrations();
-        if (applied.length === 0)
-            return null;
-        const latest = applied[applied.length - 1];
-        if (!latest)
-            return null;
-        const migration = this.migrations.find((c) => c.version === latest.version);
-        if (!migration) {
-            throw new DatabaseError(`Migration "${latest.name}" is recorded as applied but is not registered.`, {
-                metadata: { version: latest.version },
-            });
+    /**
+     * Alias of {@link migrate}.
+     */
+    run() {
+        return this.migrate();
+    }
+    async rollback(steps) {
+        if (steps === undefined) {
+            const [record] = await this.rollbackSteps(1);
+            return record ?? null;
         }
-        if (!migration.down) {
-            throw new DatabaseError(`Migration "${migration.name}" does not define a rollback operation.`, {
-                metadata: { version: migration.version },
-            });
+        if (!Number.isInteger(steps) || steps <= 0) {
+            throw new TypeError("Rollback steps must be a positive integer.");
         }
-        await this.client.transaction(async (transaction) => {
-            await this.acquireMigrationLock(transaction);
-            await migration.down(transaction);
-            await this.deleteMigrationRecord(transaction, migration.version);
-        });
-        return latest;
+        return this.rollbackSteps(steps);
     }
-    async rollbackAll() {
-        await this.ensureMigrationTable();
-        const applied = await this.getAppliedMigrations();
-        if (applied.length === 0)
-            return [];
-        const rolledBack = [];
-        await this.client.transaction(async (transaction) => {
-            await this.acquireMigrationLock(transaction);
-            for (let index = applied.length - 1; index >= 0; index -= 1) {
-                const record = applied[index];
-                if (!record)
-                    continue;
-                const migration = this.migrations.find((c) => c.version === record.version);
-                if (!migration) {
-                    throw new DatabaseError(`Migration "${record.name}" is not registered.`, {
-                        metadata: { version: record.version },
-                    });
-                }
-                if (!migration.down) {
-                    throw new DatabaseError(`Migration "${migration.name}" does not define a rollback operation.`, {
-                        metadata: { version: migration.version },
-                    });
-                }
-                await migration.down(transaction);
-                await this.deleteMigrationRecord(transaction, migration.version);
-                rolledBack.push(record);
-            }
-        });
-        return rolledBack;
+    /**
+     * Reverts every applied migration, newest first.
+     */
+    rollbackAll() {
+        return this.rollbackSteps(Number.POSITIVE_INFINITY);
     }
+    /**
+     * Creates the tracking table if it does not exist.
+     */
     async ensureMigrationTable() {
-        const table = quoteIdentifier(this.tableName);
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const { bigint, varchar255, timestamp } = this.dialect.types;
+        const ddl = `CREATE TABLE IF NOT EXISTS ${q(this.tableName)} (` +
+            `${q("version")} ${bigint} PRIMARY KEY, ` +
+            `${q("name")} ${varchar255} NOT NULL, ` +
+            `${q("applied_at")} ${timestamp} NOT NULL DEFAULT ${this.dialect.currentTimestamp})`;
         try {
-            await this.client.executeRaw(Prisma.sql `CREATE TABLE IF NOT EXISTS ${table} (
-          "version" INTEGER PRIMARY KEY,
-          "name" VARCHAR(255) NOT NULL,
-          "applied_at" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-        )`);
+            await this.client.executeRawUnsafe(ddl);
         }
         catch (error) {
-            throw new DatabaseError("Failed to initialize the migration table.", {
+            throw this.migrationError("Failed to initialize the migration table.", {
                 cause: error,
                 metadata: { tableName: this.tableName },
             });
         }
     }
-    async getAppliedMigrations() {
-        const table = quoteIdentifier(this.tableName);
+    /**
+     * Returns the applied migrations ordered by version.
+     *
+     * Pass the transaction context to read inside a running transaction
+     * (for example after acquiring the advisory lock).
+     */
+    async getAppliedMigrations(transaction) {
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const sql = `SELECT ${q("version")}, ${q("name")}, ${q("applied_at")} ` +
+            `FROM ${q(this.tableName)} ORDER BY ${q("version")} ASC`;
         try {
-            const rows = await this.client.queryRaw(Prisma.sql `SELECT "version", "name", "applied_at" FROM ${table} ORDER BY "version" ASC`);
+            const rows = await this.executor(transaction).query(sql);
             return rows.map((row) => ({
                 version: Number(row.version),
                 name: row.name,
@@ -141,27 +147,105 @@ export class MigrationRunner {
             }));
         }
         catch (error) {
-            throw new DatabaseError("Failed to read migration history.", {
+            throw this.migrationError("Failed to read migration history.", {
                 cause: error,
                 metadata: { tableName: this.tableName },
             });
         }
     }
+    /**
+     * Alias of {@link getAppliedMigrations}.
+     */
+    getHistory() {
+        return this.getAppliedMigrations();
+    }
+    async rollbackSteps(limit) {
+        await this.ensureMigrationTable();
+        const rolledBack = [];
+        if (!this.perItemTransaction) {
+            await this.client.transaction(async (transaction) => {
+                await this.acquireMigrationLock(transaction);
+                const applied = [...(await this.getAppliedMigrations(transaction))];
+                while (applied.length > 0 && rolledBack.length < limit) {
+                    const record = applied.pop();
+                    await this.revertRecord(transaction, record);
+                    rolledBack.push(record);
+                }
+            }, this.buildTransactionOptions());
+            return rolledBack;
+        }
+        while (rolledBack.length < limit) {
+            const record = 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;
+            }, this.buildTransactionOptions());
+            if (!record)
+                break;
+            rolledBack.push(record);
+        }
+        return rolledBack;
+    }
+    async revertRecord(transaction, 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 } });
+        }
+        if (!migration.down) {
+            throw this.migrationError(`Migration "${migration.name}" does not define a rollback operation.`, { metadata: { version: migration.version } });
+        }
+        try {
+            await migration.down(transaction);
+        }
+        catch (error) {
+            throw this.migrationError(`Rollback of migration "${migration.name}" failed.`, {
+                cause: error,
+                metadata: { version: migration.version, name: migration.name },
+            });
+        }
+        await this.deleteMigrationRecord(transaction, migration.version);
+    }
+    computePending(applied) {
+        const versions = new Set(applied.map((record) => record.version));
+        return this.migrations.filter((m) => !versions.has(m.version));
+    }
+    buildTransactionOptions() {
+        return { ...this.transactionOptions };
+    }
+    executor(transaction) {
+        if (transaction) {
+            return {
+                query: (sql, ...values) => transaction.$queryRawUnsafe(sql, ...values),
+                execute: (sql, ...values) => transaction.$executeRawUnsafe(sql, ...values),
+            };
+        }
+        return {
+            query: (sql, ...values) => this.client.queryRawUnsafe(sql, values),
+            execute: (sql, ...values) => this.client.executeRawUnsafe(sql, values),
+        };
+    }
     async executeMigration(transaction, migration) {
         try {
             await migration.up(transaction);
         }
         catch (error) {
-            throw new DatabaseError(`Migration "${migration.name}" failed.`, {
+            throw this.migrationError(`Migration "${migration.name}" failed.`, {
                 cause: error,
                 metadata: { version: migration.version, name: migration.name },
             });
         }
     }
     async recordMigration(transaction, migration) {
-        const table = quoteIdentifier(this.tableName);
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const p = (index) => this.dialect.placeholder(index);
+        const sql = `INSERT INTO ${q(this.tableName)} (${q("version")}, ${q("name")}) ` +
+            `VALUES (${p(1)}, ${p(2)})`;
         try {
-            await transaction.$executeRawUnsafe(`INSERT INTO ${table} ("version", "name") VALUES ($1, $2)`, migration.version, migration.name);
+            await this.executor(transaction).execute(sql, BigInt(migration.version), migration.name);
             return {
                 version: migration.version,
                 name: migration.name,
@@ -169,36 +253,40 @@ export class MigrationRunner {
             };
         }
         catch (error) {
-            throw new DatabaseError(`Failed to record migration "${migration.name}".`, {
-                cause: error,
-                metadata: { version: migration.version },
-            });
+            throw this.migrationError(`Failed to record migration "${migration.name}".`, { cause: error, metadata: { version: migration.version } });
         }
     }
     async deleteMigrationRecord(transaction, version) {
-        const table = quoteIdentifier(this.tableName);
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const sql = `DELETE FROM ${q(this.tableName)} ` +
+            `WHERE ${q("version")} = ${this.dialect.placeholder(1)}`;
         try {
-            await transaction.$executeRawUnsafe(`DELETE FROM ${table} WHERE "version" = $1`, version);
+            await this.executor(transaction).execute(sql, BigInt(version));
         }
         catch (error) {
-            throw new DatabaseError(`Failed to remove migration record for version ${version}.`, {
-                cause: error,
-                metadata: { version },
-            });
+            throw this.migrationError(`Failed to remove migration record for version ${version}.`, { cause: error, metadata: { version } });
         }
     }
     async acquireMigrationLock(transaction) {
         try {
-            const lock = hashLockKey(this.lockKey);
-            await transaction.$executeRaw `SELECT pg_advisory_xact_lock(${lock})`;
+            await this.executor(transaction).execute(this.dialect.advisoryTransactionLock(), hashLockKey(this.lockKey));
         }
         catch (error) {
-            throw new DatabaseError("Failed to acquire the database migration lock.", {
-                cause: error,
-                metadata: { lockKey: this.lockKey },
-            });
+            throw this.migrationError("Failed to acquire the database migration lock.", { cause: error, metadata: { lockKey: this.lockKey } });
         }
     }
+    migrationError(message, options = {}) {
+        if (isDatabaseErrorLike(options.cause) && !options.metadata) {
+            return options.cause;
+        }
+        return new DatabaseError(message, {
+            ...options,
+            operation: DatabaseOperation.MIGRATION,
+        });
+    }
+}
+function hasVersion(records, version) {
+    return records.some((record) => record.version === version);
 }
 /**
  * Creates a migration runner.

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

@@ -0,0 +1,85 @@
+import type { DatabaseTransactionContext } from "../databaseClient/databaseClient.core.js";
+import type { TransactionOptions } from "../databaseType/databaseType.type.js";
+import type { SqlDialectName } from "./migration.dialect.js";
+/**
+ * Migration definition.
+ *
+ * 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`.
+ */
+export interface Migration {
+    readonly version: number;
+    readonly name: string;
+    /**
+     * Applies the migration.
+     */
+    readonly up: (database: DatabaseTransactionContext) => Promise<void>;
+    /**
+     * Reverts the migration.
+     */
+    readonly down?: (database: DatabaseTransactionContext) => Promise<void>;
+}
+/**
+ * Persisted migration record.
+ */
+export interface MigrationRecord {
+    readonly version: number;
+    readonly name: string;
+    readonly appliedAt: Date;
+}
+/**
+ * Migration execution result.
+ */
+export interface MigrationResult {
+    readonly applied: readonly MigrationRecord[];
+    readonly skipped: readonly MigrationRecord[];
+}
+/**
+ * Migration status.
+ */
+export interface MigrationStatus {
+    readonly currentVersion: number;
+    readonly latestVersion: number;
+    readonly pending: readonly Migration[];
+    readonly applied: readonly MigrationRecord[];
+}
+/**
+ * Transaction options accepted by the runners.
+ */
+export type RunnerTransactionOptions = Pick<TransactionOptions, "timeoutMs" | "maxWaitMs" | "isolationLevel">;
+/**
+ * Migration runner options.
+ */
+export interface MigrationRunnerOptions {
+    /**
+     * Tracking table name. Must be a plain SQL identifier.
+     */
+    readonly tableName?: string;
+    /**
+     * Advisory lock key used to serialise concurrent runners.
+     */
+    readonly lockKey?: string;
+    /**
+     * SQL dialect. Only `postgresql` is implemented.
+     */
+    readonly dialect?: SqlDialectName;
+    /**
+     * Options forwarded to every transaction the runner opens
+     * (`timeoutMs`, `maxWaitMs`, `isolationLevel`).
+     */
+    readonly transaction?: RunnerTransactionOptions;
+    /**
+     * When `true` (default) each migration runs in its own transaction, so a
+     * slow migration cannot roll back earlier ones and the Prisma transaction
+     * timeout applies per migration. When `false` the whole batch runs in one
+     * transaction and is all-or-nothing.
+     *
+     * The advisory lock is transaction-scoped: it is held for the whole run
+     * when `perItemTransaction` is `false`, and re-acquired for every
+     * migration otherwise. Applied history is always re-read under the lock,
+     * so concurrent runners never execute the same migration twice.
+     */
+    readonly perItemTransaction?: boolean;
+}
+//# sourceMappingURL=migration.types.d.ts.map

package/dist/pagination/index.d.ts

@@ -3,5 +3,6 @@
  *
  * Offset and cursor pagination utilities.
  */
-export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, } from "./pagination.core.js";
+export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, type NormalizedPagination, type CursorPaginationInput, type CursorPaginationMeta, type CursorPaginatedResult, type CursorPayload, type EncodeCursorOptions, type DecodeCursorOptions, } from "./pagination.core.js";
+export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, type KeysetPageOptions, type KeysetWhere, } from "./pagination.keyset.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/pagination/index.js

@@ -3,5 +3,6 @@
  *
  * Offset and cursor pagination utilities.
  */
-export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination.core.js";
+export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, calculateTotalPages, createPaginationMeta, createPaginatedResult, getNextPage, getPreviousPage, isValidPage, getItemRange, paginateCollection, encodeCursor, decodeCursor, validateCursorPayload, normalizeCursorPagination, createCursorPaginationMeta, createCursorPaginatedResult, DEFAULT_PAGE, DEFAULT_LIMIT, MAX_LIMIT, } from "./pagination.core.js";
+export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, } from "./pagination.keyset.js";
 //# sourceMappingURL=index.js.map