@zudojs/database 0.1.0 → 1.0.0

package/dist/locks/locks.core.js

@@ -1,10 +1,10 @@
-import { DatabaseError } from "@zudojs/errors";
+import { DatabaseError, DatabaseOperation, ErrorCode } from "@zudojs/errors";
+import { normalizeDatabaseError } from "../databaseClient/databaseClient.errors.js";
+import { fnv1a64, hashLockKey, SQL_IDENTIFIER_PATTERN, } from "../migration/migration.helpers.js";
 /**
- * Application-level lock abstraction.
+ * Application-level lock abstraction for PostgreSQL.
  *
- * Database row locks are normally acquired inside a transaction.
- * This class provides safe SQL generation for PostgreSQL-compatible
- * databases without interpolating untrusted values into SQL.
+ * Locks are acquired inside a transaction and released when it ends.
  */
 export class DatabaseLockManager {
     client;
@@ -17,37 +17,37 @@ export class DatabaseLockManager {
     /**
      * Executes work inside a transaction after acquiring a PostgreSQL
      * advisory transaction lock.
-     *
-     * The lock is automatically released by PostgreSQL when the
-     * transaction ends.
      */
     async withAdvisoryLock(lockKey, callback, options = {}) {
         validateLockKey(lockKey);
-        if (typeof callback !== "function") {
-            throw new DatabaseError("A lock callback is required.");
-        }
+        validateCallback(callback);
         return this.client.transaction(async (transaction) => {
             await acquireAdvisoryLock(transaction, lockKey, options);
             return callback(transaction);
-        });
+        }, resolveLockTransactionOptions(options));
     }
     /**
-     * Acquires a row-level lock and executes work against the supplied
-     * table and identifier.
+     * Acquires a row-level lock and executes work while holding it.
      *
-     * The table name is validated as an SQL identifier before being
-     * interpolated into the query.
+     * @throws {DatabaseError} when the row does not exist or was skipped
+     * because another transaction holds it (`skipLocked`).
      */
     async withRowLock(tableName, id, callback, options = {}) {
         validateIdentifier(tableName, "table name");
         validateId(id);
-        if (typeof callback !== "function") {
-            throw new DatabaseError("A lock callback is required.");
-        }
+        validateCallback(callback);
         return this.client.transaction(async (transaction) => {
-            await lockRow(transaction, tableName, id, options);
+            const lock = await lockRow(transaction, tableName, id, options);
+            if (!lock.acquired) {
+                throw new DatabaseError(`Row ${String(id)} in "${tableName}" is locked by another transaction.`, {
+                    code: ErrorCode.CONFLICT,
+                    statusCode: 409,
+                    operation: DatabaseOperation.QUERY,
+                    metadata: { tableName, id, mode: lock.mode ?? null, skipped: true },
+                });
+            }
             return callback(transaction);
-        });
+        }, resolveLockTransactionOptions(options));
     }
     /**
      * Returns the underlying database client.
@@ -65,61 +65,75 @@ export function createLockManager(client) {
 /**
  * Acquires a PostgreSQL advisory transaction lock.
  *
- * The lock key is converted to a deterministic 64-bit advisory key.
+ * The lock key is hashed with FNV-1a to a signed 64-bit key (or, with a
+ * `namespace`, to a pair of signed 32-bit keys).
  */
 export async function acquireAdvisoryLock(transaction, lockKey, options = {}) {
     validateLockKey(lockKey);
-    const key = normalizeAdvisoryKey(lockKey);
+    const useNamespace = options.namespace !== undefined;
+    if (useNamespace)
+        validateLockKey(options.namespace, "lock namespace");
+    const fn = options.noWait ? "pg_try_advisory_xact_lock" : "pg_advisory_xact_lock";
+    const sql = useNamespace
+        ? `SELECT ${fn}($1, $2) AS acquired`
+        : `SELECT ${fn}($1) AS acquired`;
+    const values = useNamespace
+        ? normalizeAdvisoryKeyPair(options.namespace, lockKey)
+        : [normalizeAdvisoryKey(lockKey)];
     try {
-        if (options.noWait) {
-            const acquired = await transaction.$queryRaw `
-          SELECT pg_try_advisory_xact_lock(
-            ${key}
-          ) AS acquired
-        `;
-            if (!acquired[0]?.acquired) {
-                throw new DatabaseError(`Database advisory lock "${lockKey}" is already held.`);
-            }
-            return;
+        await applyLockTimeout(transaction, options.timeoutMs);
+        const rows = await transaction.$queryRawUnsafe(sql, ...values);
+        if (options.noWait && rows[0]?.acquired !== true) {
+            throw new DatabaseError(`Database advisory lock "${lockKey}" is already held.`, {
+                code: ErrorCode.CONFLICT,
+                statusCode: 409,
+                operation: DatabaseOperation.QUERY,
+                metadata: { lockKey, namespace: options.namespace ?? null },
+            });
         }
-        await transaction.$executeRaw `
-      SELECT pg_advisory_xact_lock(
-        ${key}
-      )
-    `;
+        return { acquired: true, lockKey };
     }
     catch (error) {
-        if (error instanceof DatabaseError) {
-            throw error;
-        }
-        throw new DatabaseError(`Failed to acquire database advisory lock "${lockKey}".`, {
-            cause: error,
-            metadata: {
-                lockKey,
-                mode: options.mode ?? "for-update",
-            },
+        throw normalizeDatabaseError(error, {
+            operation: DatabaseOperation.QUERY,
+            fallbackMessage: `Failed to acquire database advisory lock "${lockKey}".`,
+            metadata: { lockKey, namespace: options.namespace ?? null },
         });
     }
 }
 /**
  * Acquires a row-level PostgreSQL lock.
+ *
+ * @throws {DatabaseError} when the row does not exist.
+ * @returns `acquired: false` only when `skipLocked` skipped a row held by
+ * another transaction.
  */
 export async function lockRow(transaction, tableName, id, options = {}) {
     validateIdentifier(tableName, "table name");
     validateId(id);
     const mode = options.mode ?? "for-update";
     const clause = buildLockClause(mode, options);
+    const lockKey = `${tableName}:${String(id)}`;
     try {
-        await transaction.$executeRawUnsafe(`SELECT 1 FROM "${tableName}" WHERE "id" = $1 ${clause}`, id);
+        await applyLockTimeout(transaction, options.timeoutMs);
+        const rows = await transaction.$queryRawUnsafe(`SELECT 1 FROM "${tableName}" WHERE "id" = $1 ${clause}`, id);
+        if (rows.length > 0)
+            return { acquired: true, lockKey, mode };
+        if (options.skipLocked)
+            return { acquired: false, lockKey, mode };
+        throw new DatabaseError(`Row ${String(id)} in "${tableName}" was not found.`, {
+            code: ErrorCode.RESOURCE_NOT_FOUND,
+            statusCode: 404,
+            expose: true,
+            operation: DatabaseOperation.QUERY,
+            metadata: { tableName, id, mode },
+        });
     }
     catch (error) {
-        throw new DatabaseError(`Failed to acquire row lock on "${tableName}".`, {
-            cause: error,
-            metadata: {
-                tableName,
-                id,
-                mode,
-            },
+        throw normalizeDatabaseError(error, {
+            operation: DatabaseOperation.QUERY,
+            fallbackMessage: `Failed to acquire row lock on "${tableName}".`,
+            metadata: { tableName, id, mode },
         });
     }
 }
@@ -129,17 +143,12 @@ export async function lockRow(transaction, tableName, id, options = {}) {
 export function buildLockClause(mode, options = {}) {
     const lockMode = getLockModeSql(mode);
     const modifiers = [];
-    if (options.noWait) {
+    if (options.noWait)
         modifiers.push("NOWAIT");
-    }
-    else if (options.skipLocked) {
+    else if (options.skipLocked)
         modifiers.push("SKIP LOCKED");
-    }
     return [lockMode, ...modifiers].join(" ");
 }
-/**
- * Maps the public lock mode to PostgreSQL SQL.
- */
 function getLockModeSql(mode) {
     switch (mode) {
         case "for-update":
@@ -155,44 +164,91 @@ function getLockModeSql(mode) {
     }
 }
 /**
- * Converts an application lock key into a deterministic signed
- * 64-bit integer represented as a bigint.
+ * Converts an application lock key into a deterministic signed 64-bit
+ * advisory key (FNV-1a 64).
  */
 export function normalizeAdvisoryKey(lockKey) {
     validateLockKey(lockKey);
-    const bytes = new TextEncoder().encode(lockKey);
-    let hash = 1469598103934665603n;
-    for (const byte of bytes) {
-        hash ^= BigInt(byte);
-        hash = BigInt.asIntN(64, hash * 1099511628211n);
+    return hashLockKey(lockKey);
+}
+/**
+ * Converts a namespace and key into the two signed 32-bit integers used by
+ * the two-argument advisory lock functions.
+ */
+export function normalizeAdvisoryKeyPair(namespace, lockKey) {
+    validateLockKey(namespace, "lock namespace");
+    validateLockKey(lockKey);
+    return [toInt32(fnv1a64(namespace)), toInt32(fnv1a64(lockKey))];
+}
+function toInt32(value) {
+    return Number(BigInt.asIntN(32, value ^ (value >> 32n)));
+}
+/**
+ * Prisma's default interactive-transaction timeout.
+ */
+const DEFAULT_PRISMA_TRANSACTION_TIMEOUT_MS = 5_000;
+/**
+ * Derives the transaction options for a lock so that `lock_timeout` is
+ * always shorter than the surrounding Prisma transaction timeout.
+ *
+ * Without this, a lock wait longer than Prisma's 5 s default would surface
+ * as a generic "transaction already closed" error instead of a lock
+ * timeout. When `transaction.timeoutMs` is not supplied it is raised to
+ * cover the lock wait plus the default budget for the callback.
+ *
+ * @throws {TypeError} when `transaction.timeoutMs` is explicitly shorter
+ * than `timeoutMs`.
+ */
+export function resolveLockTransactionOptions(options = {}) {
+    const { timeoutMs, transaction } = options;
+    if (timeoutMs === undefined)
+        return transaction;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new TypeError("Lock timeoutMs must be a non-negative finite number.");
     }
-    return BigInt.asIntN(64, hash);
+    const explicit = transaction?.timeoutMs;
+    if (explicit !== undefined) {
+        if (explicit <= timeoutMs) {
+            throw new TypeError(`Lock timeoutMs (${timeoutMs}) must be shorter than transaction.timeoutMs (${explicit}).`);
+        }
+        return transaction;
+    }
+    if (timeoutMs < DEFAULT_PRISMA_TRANSACTION_TIMEOUT_MS)
+        return transaction;
+    return {
+        ...transaction,
+        timeoutMs: Math.floor(timeoutMs) + DEFAULT_PRISMA_TRANSACTION_TIMEOUT_MS,
+    };
 }
 /**
- * Validates an advisory lock key.
+ * Applies `SET LOCAL lock_timeout` for the current transaction.
  */
-function validateLockKey(lockKey) {
+async function applyLockTimeout(transaction, timeoutMs) {
+    if (timeoutMs === undefined)
+        return;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new TypeError("Lock timeoutMs must be a non-negative finite number.");
+    }
+    await transaction.$executeRawUnsafe(`SET LOCAL lock_timeout = ${Math.floor(timeoutMs)}`);
+}
+function validateCallback(callback) {
+    if (typeof callback !== "function") {
+        throw new TypeError("A lock callback is required.");
+    }
+}
+function validateLockKey(lockKey, name = "lock key") {
     if (typeof lockKey !== "string" || lockKey.trim().length === 0) {
-        throw new TypeError("A non-empty database lock key is required.");
+        throw new TypeError(`A non-empty database ${name} is required.`);
     }
     if (lockKey.length > 255) {
-        throw new TypeError("Database lock keys cannot exceed 255 characters.");
+        throw new TypeError(`Database ${name}s cannot exceed 255 characters.`);
     }
 }
-/**
- * Validates an SQL identifier.
- */
 function validateIdentifier(value, name) {
-    if (typeof value !== "string" || value.length === 0) {
-        throw new TypeError(`A valid ${name} is required.`);
-    }
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
-        throw new TypeError(`Invalid ${name}: "${value}".`);
+    if (typeof value !== "string" || !SQL_IDENTIFIER_PATTERN.test(value)) {
+        throw new TypeError(`Invalid ${name}: "${String(value)}".`);
     }
 }
-/**
- * Validates a database identifier value.
- */
 function validateId(id) {
     if (typeof id === "string" && id.trim().length === 0) {
         throw new TypeError("A non-empty database identifier is required.");
@@ -200,5 +256,8 @@ function validateId(id) {
     if (typeof id === "number" && !Number.isFinite(id)) {
         throw new TypeError("A finite database identifier is required.");
     }
+    if (typeof id !== "string" && typeof id !== "number") {
+        throw new TypeError("A database identifier must be a string or number.");
+    }
 }
 //# sourceMappingURL=locks.core.js.map

package/dist/migration/index.d.ts

@@ -3,5 +3,7 @@
  *
  * Database migration runner with version tracking.
  */
-export { MigrationRunner, createMigrationRunner, normalizeMigrations, validateMigration, getLatestVersion, getCurrentVersion, DEFAULT_MIGRATION_TABLE, DEFAULT_MIGRATION_LOCK, type Migration, type MigrationRecord, type MigrationResult, type MigrationStatus, type MigrationRunnerOptions, } from "./migration.runner.js";
+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

@@ -4,4 +4,6 @@
  * Database migration runner with version tracking.
  */
 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

@@ -0,0 +1,65 @@
+import { DatabaseError } from "@zudojs/errors";
+/**
+ * SQL dialects known to the migration and seed runners.
+ *
+ * Only `postgresql` is implemented today. Requesting any other dialect
+ * throws an {@link UnsupportedDialectError} so callers fail loudly instead
+ * of running PostgreSQL syntax against another engine.
+ */
+export type SqlDialectName = "postgresql" | "mysql" | "sqlite";
+/**
+ * Dialect strategy used to build the small amount of raw SQL the runners
+ * need (tracking tables, history queries, and advisory locks).
+ */
+export interface SqlDialect {
+    readonly name: SqlDialectName;
+    /**
+     * Quotes a validated identifier (table or column name).
+     */
+    quoteIdentifier(identifier: string): string;
+    /**
+     * Returns the positional placeholder for the 1-based parameter index.
+     */
+    placeholder(index: number): string;
+    /**
+     * Column type names used by the tracking tables.
+     */
+    readonly types: {
+        readonly bigint: string;
+        readonly varchar255: string;
+        readonly timestamp: string;
+    };
+    /**
+     * Returns the SQL used to acquire a transaction-scoped advisory lock.
+     *
+     * The statement must accept exactly one 64-bit integer parameter.
+     */
+    advisoryTransactionLock(): string;
+    /**
+     * Default expression for the current timestamp.
+     */
+    readonly currentTimestamp: string;
+}
+/**
+ * Raised when a dialect is requested that the runners do not implement.
+ */
+export declare class UnsupportedDialectError extends DatabaseError {
+    constructor(dialect: string);
+}
+/**
+ * Default dialect used by the runners.
+ */
+export declare const DEFAULT_SQL_DIALECT: SqlDialectName;
+/**
+ * Checks whether a value names a known dialect.
+ */
+export declare function isSqlDialectName(value: unknown): value is SqlDialectName;
+/**
+ * Resolves a dialect strategy by name.
+ *
+ * @throws {UnsupportedDialectError} for `mysql` and `sqlite`, which are
+ * recognised but not implemented.
+ * @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

@@ -0,0 +1,63 @@
+import { DatabaseError } from "@zudojs/errors";
+import { validateIdentifier } from "./migration.helpers.js";
+/**
+ * Raised when a dialect is requested that the runners do not implement.
+ */
+export class UnsupportedDialectError extends DatabaseError {
+    constructor(dialect) {
+        super(`SQL dialect "${dialect}" is not supported by the migration and seed runners. Only "postgresql" is implemented.`, {
+            metadata: { dialect },
+            statusCode: 500,
+        });
+        this.name = "UnsupportedDialectError";
+    }
+}
+const POSTGRESQL_DIALECT = Object.freeze({
+    name: "postgresql",
+    quoteIdentifier(identifier) {
+        validateIdentifier(identifier, "identifier");
+        return `"${identifier}"`;
+    },
+    placeholder(index) {
+        if (!Number.isInteger(index) || index < 1) {
+            throw new TypeError("Placeholder index must be a positive integer.");
+        }
+        return `$${index}`;
+    },
+    types: Object.freeze({
+        bigint: "BIGINT",
+        varchar255: "VARCHAR(255)",
+        timestamp: "TIMESTAMP",
+    }),
+    advisoryTransactionLock() {
+        return "SELECT pg_advisory_xact_lock($1)";
+    },
+    currentTimestamp: "CURRENT_TIMESTAMP",
+});
+/**
+ * Default dialect used by the runners.
+ */
+export const DEFAULT_SQL_DIALECT = "postgresql";
+/**
+ * Checks whether a value names a known dialect.
+ */
+export function isSqlDialectName(value) {
+    return value === "postgresql" || value === "mysql" || value === "sqlite";
+}
+/**
+ * Resolves a dialect strategy by name.
+ *
+ * @throws {UnsupportedDialectError} for `mysql` and `sqlite`, which are
+ * recognised but not implemented.
+ * @throws {TypeError} for unknown dialect names.
+ */
+export function getSqlDialect(name = DEFAULT_SQL_DIALECT) {
+    if (name === "postgresql") {
+        return POSTGRESQL_DIALECT;
+    }
+    if (isSqlDialectName(name)) {
+        throw new UnsupportedDialectError(name);
+    }
+    throw new TypeError(`Unknown SQL dialect: "${String(name)}".`);
+}
+//# sourceMappingURL=migration.dialect.js.map

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

@@ -0,0 +1,65 @@
+import type { Migration, MigrationRecord } from "./migration.types.js";
+/**
+ * Default migration table.
+ */
+export declare const DEFAULT_MIGRATION_TABLE = "_migrations";
+/**
+ * Default migration advisory lock.
+ */
+export declare const DEFAULT_MIGRATION_LOCK = "database:migrations";
+/**
+ * Strict SQL identifier pattern shared by the runners.
+ */
+export declare const SQL_IDENTIFIER_PATTERN: RegExp;
+/**
+ * Normalizes and validates migrations.
+ */
+export declare function normalizeMigrations(migrations: readonly Migration[]): readonly Migration[];
+/**
+ * Validates one migration.
+ */
+export declare function validateMigration(migration: Migration): void;
+/**
+ * Returns the highest registered migration version.
+ */
+export declare function getLatestVersion(migrations: readonly Migration[]): number;
+/**
+ * Returns the highest applied migration version.
+ */
+export declare function getCurrentVersion(migrations: readonly MigrationRecord[]): number;
+/**
+ * Quotes a validated SQL identifier using double quotes.
+ *
+ * Prefer `SqlDialect.quoteIdentifier` when a dialect is available.
+ */
+export declare function quoteIdentifier(identifier: string): string;
+/**
+ * Validates an SQL identifier against {@link SQL_IDENTIFIER_PATTERN}.
+ */
+export declare function validateIdentifier(identifier: string, name: string): void;
+/**
+ * Validates an advisory lock key.
+ */
+export declare function validateLockKey(lockKey: string, name?: string): void;
+/**
+ * FNV-1a 64-bit offset basis (0xcbf29ce484222325).
+ */
+export declare const FNV1A_64_OFFSET_BASIS = 14695981039346656037n;
+/**
+ * FNV-1a 64-bit prime (0x100000001b3).
+ */
+export declare const FNV1A_64_PRIME = 1099511628211n;
+/**
+ * Computes the unsigned FNV-1a 64-bit hash of a string (UTF-8 bytes).
+ *
+ * Matches FNV-1a implementations in other languages, so lock keys can be
+ * shared with services outside this package.
+ */
+export declare function fnv1a64(value: string): bigint;
+/**
+ * Creates a deterministic signed 64-bit advisory lock key (FNV-1a).
+ *
+ * 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

@@ -6,6 +6,10 @@ export const DEFAULT_MIGRATION_TABLE = "_migrations";
  * Default migration advisory lock.
  */
 export const DEFAULT_MIGRATION_LOCK = "database:migrations";
+/**
+ * Strict SQL identifier pattern shared by the runners.
+ */
+export const SQL_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
  * Normalizes and validates migrations.
  */
@@ -38,6 +42,9 @@ export function validateMigration(migration) {
     if (!Number.isInteger(migration.version) || migration.version <= 0) {
         throw new TypeError("Migration version must be a positive integer.");
     }
+    if (migration.version > Number.MAX_SAFE_INTEGER) {
+        throw new TypeError(`Migration version ${migration.version} exceeds Number.MAX_SAFE_INTEGER.`);
+    }
     if (typeof migration.name !== "string" ||
         migration.name.trim().length === 0) {
         throw new TypeError("Migration name is required.");
@@ -53,47 +60,82 @@ export function validateMigration(migration) {
     }
 }
 /**
- * Returns the latest registered migration version.
+ * Returns the highest registered migration version.
  */
 export function getLatestVersion(migrations) {
-    if (migrations.length === 0)
-        return 0;
-    return migrations[migrations.length - 1].version;
+    let latest = 0;
+    for (const migration of migrations) {
+        if (migration.version > latest)
+            latest = migration.version;
+    }
+    return latest;
 }
 /**
- * Returns the current applied migration version.
+ * Returns the highest applied migration version.
  */
 export function getCurrentVersion(migrations) {
-    if (migrations.length === 0)
-        return 0;
-    return migrations[migrations.length - 1].version;
+    let current = 0;
+    for (const record of migrations) {
+        if (record.version > current)
+            current = record.version;
+    }
+    return current;
 }
 /**
- * Quotes a validated SQL identifier.
+ * Quotes a validated SQL identifier using double quotes.
+ *
+ * Prefer `SqlDialect.quoteIdentifier` when a dialect is available.
  */
 export function quoteIdentifier(identifier) {
     validateIdentifier(identifier, "identifier");
     return `"${identifier}"`;
 }
 /**
- * Validates an SQL identifier.
+ * Validates an SQL identifier against {@link SQL_IDENTIFIER_PATTERN}.
  */
 export function validateIdentifier(identifier, name) {
-    if (typeof identifier !== "string" ||
-        !/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
-        throw new TypeError(`Invalid ${name}: "${identifier}".`);
+    if (typeof identifier !== "string" || !SQL_IDENTIFIER_PATTERN.test(identifier)) {
+        throw new TypeError(`Invalid ${name}: "${String(identifier)}".`);
     }
 }
 /**
- * Creates a deterministic signed 64-bit advisory lock key.
+ * Validates an advisory lock key.
  */
-export function hashLockKey(value) {
-    let hash = 1469598103934665603n;
+export function validateLockKey(lockKey, name = "lock key") {
+    if (typeof lockKey !== "string" || lockKey.trim().length === 0) {
+        throw new TypeError(`A database ${name} is required.`);
+    }
+}
+/**
+ * FNV-1a 64-bit offset basis (0xcbf29ce484222325).
+ */
+export const FNV1A_64_OFFSET_BASIS = 14695981039346656037n;
+/**
+ * FNV-1a 64-bit prime (0x100000001b3).
+ */
+export const FNV1A_64_PRIME = 1099511628211n;
+const UINT64_MASK = (1n << 64n) - 1n;
+/**
+ * Computes the unsigned FNV-1a 64-bit hash of a string (UTF-8 bytes).
+ *
+ * Matches FNV-1a implementations in other languages, so lock keys can be
+ * shared with services outside this package.
+ */
+export function fnv1a64(value) {
+    let hash = FNV1A_64_OFFSET_BASIS;
     const bytes = new TextEncoder().encode(value);
     for (const byte of bytes) {
         hash ^= BigInt(byte);
-        hash = BigInt.asIntN(64, hash * 1099511628211n);
+        hash = (hash * FNV1A_64_PRIME) & UINT64_MASK;
     }
-    return BigInt.asIntN(64, hash);
+    return hash;
+}
+/**
+ * Creates a deterministic signed 64-bit advisory lock key (FNV-1a).
+ *
+ * Suitable as the single `bigint` argument of `pg_advisory_xact_lock`.
+ */
+export function hashLockKey(value) {
+    return BigInt.asIntN(64, fnv1a64(value));
 }
 //# sourceMappingURL=migration.helpers.js.map