@zudojs/database 0.1.0 → 1.0.0

package/dist/seed/seed.runner.js

@@ -1,5 +1,7 @@
-import { DatabaseError } from "@zudojs/errors";
-import { Prisma } from "@prisma/client";
+import { DatabaseError, DatabaseOperation, } from "@zudojs/errors";
+import { isDatabaseErrorLike } from "../databaseClient/databaseClient.errors.js";
+import { getSqlDialect } from "../migration/migration.dialect.js";
+import { hashLockKey, validateIdentifier, validateLockKey, } from "../migration/migration.helpers.js";
 /**
  * Default seed tracking table.
  */
@@ -10,22 +12,31 @@ export const DEFAULT_SEED_TABLE = "_seeds";
 export const DEFAULT_SEED_LOCK = "database:seeds";
 /**
  * Runs and tracks database seeds.
+ *
+ * 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 seed twice.
  */
 export class SeedRunner {
     client;
     seeds;
     tableName;
     lockKey;
+    dialect;
+    transactionOptions;
+    perItemTransaction;
     constructor(client, seeds, options = {}) {
-        if (!client) {
+        if (!client)
             throw new TypeError("A database client is required.");
-        }
         this.client = client;
         this.seeds = normalizeSeeds(seeds);
         this.tableName = options.tableName ?? DEFAULT_SEED_TABLE;
         this.lockKey = options.lockKey ?? DEFAULT_SEED_LOCK;
+        this.dialect = getSqlDialect(options.dialect);
+        this.transactionOptions = { ...options.transaction };
+        this.perItemTransaction = options.perItemTransaction ?? true;
         validateIdentifier(this.tableName, "seed table name");
-        validateLockKey(this.lockKey);
+        validateLockKey(this.lockKey, "seed lock key");
     }
     /**
      * Returns the seed runner status.
@@ -33,276 +44,275 @@ export class SeedRunner {
     async status() {
         await this.ensureSeedTable();
         const applied = await this.getAppliedSeeds();
-        const appliedNames = new Set(applied.map((seed) => seed.name));
-        const pending = this.seeds.filter((seed) => !appliedNames.has(seed.name));
-        return {
-            pending,
-            applied,
-        };
+        return { pending: this.computePending(applied), applied };
     }
     /**
-     * Executes every pending seed.
+     * Executes every pending seed in order.
      */
     async run() {
         await this.ensureSeedTable();
-        const applied = await this.getAppliedSeeds();
-        const appliedNames = new Set(applied.map((seed) => seed.name));
-        const pending = this.seeds.filter((seed) => !appliedNames.has(seed.name));
-        if (pending.length === 0) {
-            return {
-                applied: [],
-                skipped: applied,
-            };
-        }
+        const before = await this.getAppliedSeeds();
+        const pending = this.computePending(before);
+        if (pending.length === 0)
+            return { applied: [], skipped: before };
         const newlyApplied = [];
-        await this.client.transaction(async (transaction) => {
-            await this.acquireSeedLock(transaction);
-            for (const seed of pending) {
+        const skipped = [...before];
+        if (!this.perItemTransaction) {
+            await this.client.transaction(async (transaction) => {
+                await this.acquireSeedLock(transaction);
+                const applied = await this.getAppliedSeeds(transaction);
+                skipped.push(...applied.filter((r) => !hasName(before, r.name)));
+                for (const seed of this.computePending(applied)) {
+                    await this.executeSeed(transaction, seed);
+                    newlyApplied.push(await this.recordSeed(transaction, seed));
+                }
+            }, this.buildTransactionOptions());
+            return { applied: newlyApplied, skipped };
+        }
+        for (const seed of pending) {
+            const outcome = await this.client.transaction(async (transaction) => {
+                await this.acquireSeedLock(transaction);
+                const applied = await this.getAppliedSeeds(transaction);
+                const existing = applied.find((r) => r.name === seed.name);
+                if (existing)
+                    return { record: existing, skipped: true };
                 await this.executeSeed(transaction, seed);
                 const record = await this.recordSeed(transaction, seed);
-                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 };
     }
     /**
-     * Executes one named seed.
+     * Executes one named seed. Returns the existing record when already
+     * applied.
      */
     async runOne(name) {
         validateSeedName(name);
         await this.ensureSeedTable();
         const seed = this.seeds.find((candidate) => candidate.name === name);
         if (!seed) {
-            throw new DatabaseError(`Seed "${name}" is not registered.`);
-        }
-        const applied = await this.getAppliedSeeds();
-        const existing = applied.find((record) => record.name === name);
-        if (existing) {
-            return existing;
+            throw this.seedError(`Seed "${name}" is not registered.`, {
+                metadata: { name },
+            });
         }
-        let result;
-        await this.client.transaction(async (transaction) => {
+        return this.client.transaction(async (transaction) => {
             await this.acquireSeedLock(transaction);
             const current = await this.getAppliedSeeds(transaction);
             const alreadyApplied = current.find((record) => record.name === name);
-            if (alreadyApplied) {
-                result = alreadyApplied;
-                return;
-            }
+            if (alreadyApplied)
+                return alreadyApplied;
             await this.executeSeed(transaction, seed);
-            result = await this.recordSeed(transaction, seed);
-        });
-        if (!result) {
-            throw new DatabaseError(`Seed "${name}" did not produce an execution record.`);
-        }
-        return result;
+            return this.recordSeed(transaction, seed);
+        }, this.buildTransactionOptions());
     }
     /**
      * Rolls back the most recently applied seed.
      */
     async rollback() {
-        await this.ensureSeedTable();
-        const applied = await this.getAppliedSeeds();
-        if (applied.length === 0) {
-            return null;
-        }
-        const latest = applied[applied.length - 1];
-        if (!latest) {
-            return null;
-        }
-        const seed = this.seeds.find((candidate) => candidate.name === latest.name);
-        if (!seed) {
-            throw new DatabaseError(`Seed "${latest.name}" is recorded as applied but is not registered.`);
-        }
-        if (!seed.rollback) {
-            throw new DatabaseError(`Seed "${seed.name}" does not define a rollback operation.`);
-        }
-        await this.client.transaction(async (transaction) => {
-            await this.acquireSeedLock(transaction);
-            await seed.rollback(transaction);
-            await this.deleteSeedRecord(transaction, seed.name);
-        });
-        return latest;
+        const [record] = await this.rollbackSteps(1);
+        return record ?? null;
     }
     /**
      * Rolls back every applied seed in reverse execution order.
      */
-    async rollbackAll() {
-        await this.ensureSeedTable();
-        const applied = await this.getAppliedSeeds();
-        if (applied.length === 0) {
-            return [];
-        }
-        const rolledBack = [];
-        await this.client.transaction(async (transaction) => {
-            await this.acquireSeedLock(transaction);
-            for (let index = applied.length - 1; index >= 0; index -= 1) {
-                const record = applied[index];
-                if (!record) {
-                    continue;
-                }
-                const seed = this.seeds.find((candidate) => candidate.name === record.name);
-                if (!seed) {
-                    throw new DatabaseError(`Seed "${record.name}" is not registered.`);
-                }
-                if (!seed.rollback) {
-                    throw new DatabaseError(`Seed "${seed.name}" does not define a rollback operation.`);
-                }
-                await seed.rollback(transaction);
-                await this.deleteSeedRecord(transaction, seed.name);
-                rolledBack.push(record);
-            }
-        });
-        return rolledBack;
+    rollbackAll() {
+        return this.rollbackSteps(Number.POSITIVE_INFINITY);
     }
     /**
-     * Creates the seed tracking table if it does not exist.
+     * Creates the seed tracking table if it does not exist, adding the
+     * `sequence` column to tables created by earlier versions.
      */
     async ensureSeedTable() {
-        const table = quoteIdentifier(this.tableName);
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const { varchar255, timestamp } = this.dialect.types;
+        const ddl = `CREATE TABLE IF NOT EXISTS ${q(this.tableName)} (` +
+            `${q("name")} ${varchar255} PRIMARY KEY, ` +
+            `${q("applied_at")} ${timestamp} NOT NULL DEFAULT ${this.dialect.currentTimestamp}, ` +
+            `${q("sequence")} BIGSERIAL NOT NULL)`;
+        const upgrade = `ALTER TABLE ${q(this.tableName)} ` +
+            `ADD COLUMN IF NOT EXISTS ${q("sequence")} BIGSERIAL NOT NULL`;
         try {
-            await this.client.executeRaw(Prisma.sql `
-          CREATE TABLE IF NOT EXISTS ${table} (
-            "name" VARCHAR(255) PRIMARY KEY,
-            "applied_at" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-          )
-        `);
+            await this.client.executeRawUnsafe(ddl);
+            await this.client.executeRawUnsafe(upgrade);
         }
         catch (error) {
-            throw new DatabaseError("Failed to initialize the seed tracking table.", {
+            throw this.seedError("Failed to initialize the seed tracking table.", {
                 cause: error,
-                metadata: {
-                    tableName: this.tableName,
-                },
+                metadata: { tableName: this.tableName },
             });
         }
     }
     /**
-     * Returns all applied seeds.
+     * Returns all applied seeds ordered by execution sequence.
      */
     async getAppliedSeeds(transaction) {
-        const table = quoteIdentifier(this.tableName);
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const sql = `SELECT ${q("name")}, ${q("applied_at")}, ${q("sequence")} ` +
+            `FROM ${q(this.tableName)} ORDER BY ${q("sequence")} ASC`;
         try {
-            let rows;
-            if (transaction) {
-                rows = await transaction.$queryRawUnsafe(`
-          SELECT
-            "name",
-            "applied_at"
-          FROM ${table}
-          ORDER BY "applied_at" ASC, "name" ASC
-        `);
-            }
-            else {
-                rows = await this.client.queryRaw(Prisma.sql `
-            SELECT
-              "name",
-              "applied_at"
-            FROM ${table}
-            ORDER BY "applied_at" ASC, "name" ASC
-          `);
-            }
+            const rows = await this.executor(transaction).query(sql);
             return rows.map((row) => ({
                 name: row.name,
                 appliedAt: new Date(row.applied_at),
+                sequence: Number(row.sequence),
             }));
         }
         catch (error) {
-            throw new DatabaseError("Failed to read seed execution history.", {
+            throw this.seedError("Failed to read seed execution history.", {
                 cause: error,
-                metadata: {
-                    tableName: this.tableName,
-                },
+                metadata: { tableName: this.tableName },
             });
         }
     }
     /**
-     * Executes a seed.
+     * Alias of {@link getAppliedSeeds}.
      */
+    getHistory() {
+        return this.getAppliedSeeds();
+    }
+    async rollbackSteps(limit) {
+        await this.ensureSeedTable();
+        const rolledBack = [];
+        if (!this.perItemTransaction) {
+            await this.client.transaction(async (transaction) => {
+                await this.acquireSeedLock(transaction);
+                const applied = [...(await this.getAppliedSeeds(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.acquireSeedLock(transaction);
+                const applied = await this.getAppliedSeeds(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 seed = this.seeds.find((candidate) => candidate.name === record.name);
+        if (!seed) {
+            throw this.seedError(`Seed "${record.name}" is recorded as applied but is not registered.`, { metadata: { name: record.name } });
+        }
+        if (!seed.rollback) {
+            throw this.seedError(`Seed "${seed.name}" does not define a rollback operation.`, { metadata: { name: seed.name } });
+        }
+        try {
+            await seed.rollback(transaction);
+        }
+        catch (error) {
+            throw this.seedError(`Rollback of seed "${seed.name}" failed.`, {
+                cause: error,
+                metadata: { name: seed.name },
+            });
+        }
+        await this.deleteSeedRecord(transaction, seed.name);
+    }
+    computePending(applied) {
+        const names = new Set(applied.map((record) => record.name));
+        return this.seeds.filter((seed) => !names.has(seed.name));
+    }
+    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 executeSeed(transaction, seed) {
         try {
             await seed.run(transaction);
         }
         catch (error) {
-            throw new DatabaseError(`Seed "${seed.name}" failed.`, {
+            throw this.seedError(`Seed "${seed.name}" failed.`, {
                 cause: error,
-                metadata: {
-                    name: seed.name,
-                    order: seed.order ?? 0,
-                },
+                metadata: { name: seed.name, order: seed.order ?? 0 },
             });
         }
     }
-    /**
-     * Records a successfully executed seed.
-     */
     async recordSeed(transaction, seed) {
-        const table = quoteIdentifier(this.tableName);
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const sql = `INSERT INTO ${q(this.tableName)} (${q("name")}) ` +
+            `VALUES (${this.dialect.placeholder(1)}) ` +
+            `RETURNING ${q("name")}, ${q("applied_at")}, ${q("sequence")}`;
         try {
-            await transaction.$executeRawUnsafe(`
-          INSERT INTO ${table}
-            ("name")
-          VALUES
-            ($1)
-        `, seed.name);
+            const rows = await this.executor(transaction).query(sql, seed.name);
+            const row = rows[0];
             return {
                 name: seed.name,
-                appliedAt: new Date(),
+                appliedAt: row ? new Date(row.applied_at) : new Date(),
+                sequence: row ? Number(row.sequence) : 0,
             };
         }
         catch (error) {
-            throw new DatabaseError(`Failed to record seed "${seed.name}".`, {
+            throw this.seedError(`Failed to record seed "${seed.name}".`, {
                 cause: error,
-                metadata: {
-                    name: seed.name,
-                },
+                metadata: { name: seed.name },
             });
         }
     }
-    /**
-     * Removes a seed execution record.
-     */
     async deleteSeedRecord(transaction, name) {
-        const table = quoteIdentifier(this.tableName);
+        const q = (id) => this.dialect.quoteIdentifier(id);
+        const sql = `DELETE FROM ${q(this.tableName)} ` +
+            `WHERE ${q("name")} = ${this.dialect.placeholder(1)}`;
         try {
-            await transaction.$executeRawUnsafe(`
-          DELETE FROM ${table}
-          WHERE "name" = $1
-        `, name);
+            await this.executor(transaction).execute(sql, name);
         }
         catch (error) {
-            throw new DatabaseError(`Failed to remove seed record "${name}".`, {
+            throw this.seedError(`Failed to remove seed record "${name}".`, {
                 cause: error,
-                metadata: {
-                    name,
-                },
+                metadata: { name },
             });
         }
     }
-    /**
-     * Acquires the advisory lock used for seed execution.
-     */
     async acquireSeedLock(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 seed lock.", {
+            throw this.seedError("Failed to acquire the database seed lock.", {
                 cause: error,
-                metadata: {
-                    lockKey: this.lockKey,
-                },
+                metadata: { lockKey: this.lockKey },
             });
         }
     }
+    seedError(message, options = {}) {
+        if (isDatabaseErrorLike(options.cause) && !options.metadata) {
+            return options.cause;
+        }
+        return new DatabaseError(message, {
+            ...options,
+            operation: DatabaseOperation.MIGRATION,
+        });
+    }
+}
+function hasName(records, name) {
+    return records.some((record) => record.name === name);
 }
 /**
  * Creates a seed runner.
@@ -311,7 +321,7 @@ export function createSeedRunner(client, seeds, options) {
     return new SeedRunner(client, seeds, options);
 }
 /**
- * Validates and sorts seed definitions.
+ * Validates and sorts seed definitions (stable sort on `order`).
  */
 export function normalizeSeeds(seeds) {
     if (!Array.isArray(seeds)) {
@@ -320,9 +330,7 @@ export function normalizeSeeds(seeds) {
     const normalized = seeds
         .map((seed) => {
         validateSeed(seed);
-        return Object.freeze({
-            ...seed,
-        });
+        return Object.freeze({ ...seed });
     })
         .sort((first, second) => (first.order ?? 0) - (second.order ?? 0));
     const names = new Set();
@@ -352,9 +360,6 @@ export function validateSeed(seed) {
         throw new TypeError(`Seed "${seed.name}" has an invalid rollback function.`);
     }
 }
-/**
- * Validates a seed name.
- */
 function validateSeedName(name) {
     if (typeof name !== "string" || name.trim().length === 0) {
         throw new TypeError("Seed name is required.");
@@ -363,40 +368,4 @@ function validateSeedName(name) {
         throw new TypeError("Seed name cannot exceed 255 characters.");
     }
 }
-/**
- * Validates an SQL identifier.
- */
-function validateIdentifier(identifier, name) {
-    if (typeof identifier !== "string" ||
-        !/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
-        throw new TypeError(`Invalid ${name}: "${identifier}".`);
-    }
-}
-/**
- * Validates an advisory lock key.
- */
-function validateLockKey(lockKey) {
-    if (typeof lockKey !== "string" || lockKey.trim().length === 0) {
-        throw new TypeError("A database seed lock key is required.");
-    }
-}
-/**
- * Quotes a validated SQL identifier.
- */
-function quoteIdentifier(identifier) {
-    validateIdentifier(identifier, "identifier");
-    return `"${identifier}"`;
-}
-/**
- * Generates a deterministic signed 64-bit advisory lock key.
- */
-function hashLockKey(value) {
-    let hash = 1469598103934665603n;
-    const bytes = new TextEncoder().encode(value);
-    for (const byte of bytes) {
-        hash ^= BigInt(byte);
-        hash = BigInt.asIntN(64, hash * 1099511628211n);
-    }
-    return BigInt.asIntN(64, hash);
-}
 //# sourceMappingURL=seed.runner.js.map

package/dist/transaction/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Managed transaction execution with retry support.
  */
-export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, isTransactionActive, isTransactionCommitted, isTransactionFailed, type TransactionStatus, type TransactionContext, type ManagedTransactionOptions, } from "./transaction.core.js";
+export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, getTransactionContextFromError, isTransactionActive, isTransactionCommitted, isTransactionFailed, type TransactionStatus, type TransactionContext, type TransactionOutcome, type TransactionRetryOptions, type ManagedTransactionOptions, } from "./transaction.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/transaction/index.js

@@ -3,5 +3,5 @@
  *
  * Managed transaction execution with retry support.
  */
-export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, isTransactionActive, isTransactionCommitted, isTransactionFailed, } from "./transaction.core.js";
+export { TransactionManager, createTransactionManager, withTransaction, withTransactionRetry, createTransactionContext, createTransactionId, getTransactionContextFromError, isTransactionActive, isTransactionCommitted, isTransactionFailed, } from "./transaction.core.js";
 //# sourceMappingURL=index.js.map