@zudojs/database 0.1.0 → 1.1.0

package/dist/repository/repository.errors.js

@@ -0,0 +1,235 @@
+import { DatabaseError, DatabaseOperation, ErrorCode, } from "@zudojs/errors";
+import { isDatabaseErrorLike } from "../databaseClient/databaseClient.errors.js";
+const PRISMA_CODE_PATTERN = /^P\d{4}$/;
+/**
+ * Determines whether a value looks like a Prisma known request error.
+ */
+export function isPrismaErrorLike(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.code === "string" &&
+        PRISMA_CODE_PATTERN.test(candidate.code) &&
+        typeof candidate.message === "string");
+}
+/**
+ * Maps a repository operation name to the errors package operation enum.
+ */
+export function toDatabaseOperation(operation) {
+    switch (operation) {
+        case "create":
+        case "createMany":
+            return DatabaseOperation.INSERT;
+        case "update":
+        case "upsert":
+        case "softDelete":
+        case "restore":
+            return DatabaseOperation.UPDATE;
+        case "delete":
+        case "deleteMany":
+            return DatabaseOperation.DELETE;
+        case "findById":
+        case "findOne":
+        case "findMany":
+        case "findPaginated":
+        case "findByQuery":
+        case "paginateCursor":
+        case "findDeleted":
+        case "count":
+        case "exists":
+            return DatabaseOperation.QUERY;
+        default:
+            return DatabaseOperation.UNKNOWN;
+    }
+}
+/**
+ * Normalizes any failure raised by a repository operation into a
+ * `DatabaseError`, mapping Prisma error codes to typed outcomes:
+ *
+ * - `P2002` unique violation → `ERR_CONFLICT` / 409
+ * - `P2025` record not found → `ERR_NOT_FOUND` / 404
+ * - `P2003` foreign key violation → `ERR_CONFLICT` / 409
+ * - `P2034` serialization failure → `ERR_DATABASE_TRANSACTION` / 409 (retryable)
+ * - `P2024` pool timeout → `ERR_DATABASE_TIMEOUT` / 503
+ * - `P1xxx` connection failures → `ERR_DATABASE_CONNECTION` / 503
+ *
+ * Existing `DatabaseError`s are returned unchanged.
+ */
+export function mapRepositoryError(error, context) {
+    if (isDatabaseErrorLike(error)) {
+        return error;
+    }
+    const operation = toDatabaseOperation(context.operation);
+    const metadata = {
+        ...toErrorMetadata(context.metadata),
+        model: context.model,
+        operation: context.operation,
+        durationMs: context.durationMs,
+    };
+    const base = {
+        cause: error,
+        operation,
+        driver: "prisma",
+    };
+    if (!isPrismaErrorLike(error)) {
+        return new DatabaseError(error instanceof Error
+            ? error.message
+            : `${context.model} ${context.operation} failed.`, {
+            ...base,
+            driver: undefined,
+            metadata,
+        });
+    }
+    const target = extractTarget(error.meta);
+    if (target !== undefined) {
+        metadata["target"] = target;
+    }
+    const fieldName = error.meta?.["field_name"];
+    if (typeof fieldName === "string") {
+        metadata["field"] = fieldName;
+    }
+    const options = {
+        ...base,
+        databaseCode: error.code,
+        metadata,
+    };
+    switch (error.code) {
+        case "P2002":
+            return new DatabaseError(`${context.model} already exists.`, {
+                ...options,
+                code: ErrorCode.CONFLICT,
+                statusCode: 409,
+                expose: true,
+            });
+        case "P2025":
+            return new DatabaseError(`${context.model} was not found.`, {
+                ...options,
+                code: ErrorCode.NOT_FOUND,
+                statusCode: 404,
+                expose: true,
+            });
+        case "P2003":
+            return new DatabaseError(`${context.model} ${context.operation} violates a foreign key constraint.`, {
+                ...options,
+                code: ErrorCode.CONFLICT,
+                statusCode: 409,
+                expose: true,
+            });
+        case "P2034":
+            return new DatabaseError(`${context.model} ${context.operation} failed due to a transaction conflict.`, {
+                ...options,
+                code: ErrorCode.DATABASE_TRANSACTION,
+                statusCode: 409,
+                metadata: { ...metadata, retryable: true },
+            });
+        case "P2024":
+            return new DatabaseError(`${context.model} ${context.operation} timed out waiting for a connection.`, {
+                ...options,
+                code: ErrorCode.DATABASE_TIMEOUT,
+                statusCode: 503,
+            });
+        default:
+            break;
+    }
+    if (error.code.startsWith("P1")) {
+        return new DatabaseError(`${context.model} ${context.operation} failed: database unavailable.`, {
+            ...options,
+            code: ErrorCode.DATABASE_CONNECTION,
+            statusCode: 503,
+        });
+    }
+    return new DatabaseError(`${context.model} ${context.operation} failed.`, {
+        ...options,
+        code: ErrorCode.DATABASE_QUERY,
+    });
+}
+/**
+ * Creates the error raised when an operation is aborted via `AbortSignal`.
+ */
+export function createAbortError(context, reason) {
+    return new DatabaseError(`${context.model} ${context.operation} was aborted.`, {
+        code: ErrorCode.OPERATION_CANCELLED,
+        statusCode: 499,
+        operation: toDatabaseOperation(context.operation),
+        cause: reason,
+        metadata: {
+            ...toErrorMetadata(context.metadata),
+            model: context.model,
+            operation: context.operation,
+            aborted: true,
+        },
+    });
+}
+/**
+ * Creates the error raised when a client-side timeout elapses.
+ */
+export function createTimeoutError(context, timeoutMs) {
+    return new DatabaseError(`${context.model} ${context.operation} timed out after ${timeoutMs}ms.`, {
+        code: ErrorCode.DATABASE_TIMEOUT,
+        statusCode: 503,
+        operation: toDatabaseOperation(context.operation),
+        metadata: {
+            ...toErrorMetadata(context.metadata),
+            model: context.model,
+            operation: context.operation,
+            timeoutMs,
+        },
+    });
+}
+/**
+ * Converts arbitrary metadata into the serializable shape the errors
+ * package accepts.
+ */
+export function toErrorMetadata(value) {
+    const result = {};
+    if (!value) {
+        return result;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        result[key] = toMetadataValue(entry);
+    }
+    return result;
+}
+function toMetadataValue(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => toMetadataValue(entry) ?? null);
+    }
+    if (typeof value === "object") {
+        const result = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const converted = toMetadataValue(entry);
+            if (converted !== undefined) {
+                result[key] = converted;
+            }
+        }
+        return result;
+    }
+    return String(value);
+}
+function extractTarget(meta) {
+    const target = meta?.["target"];
+    if (typeof target === "string") {
+        return target;
+    }
+    if (Array.isArray(target)) {
+        return target.map((entry) => String(entry));
+    }
+    return undefined;
+}
+//# sourceMappingURL=repository.errors.js.map

package/dist/seed/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @zudojs/database — Seeds
  *
- * Database seed runner with execution tracking.
+ * Database seed runner with execution tracking (PostgreSQL).
  */
-export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, type Seed, type SeedRecord, type SeedResult, type SeedRunnerOptions, } from "./seed.runner.js";
+export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, type Seed, type SeedRecord, type SeedResult, type SeedStatus, type SeedRunnerOptions, } from "./seed.runner.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/seed/index.js

@@ -1,7 +1,7 @@
 /**
  * @zudojs/database — Seeds
  *
- * Database seed runner with execution tracking.
+ * Database seed runner with execution tracking (PostgreSQL).
  */
 export { SeedRunner, createSeedRunner, normalizeSeeds, validateSeed, DEFAULT_SEED_TABLE, DEFAULT_SEED_LOCK, } from "./seed.runner.js";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,160 @@
+import type { DatabaseClient, DatabaseTransactionContext } from "../databaseClient/databaseClient.core.js";
+import { type SqlDialectName } from "../migration/migration.dialect.js";
+import type { RunnerTransactionOptions } from "../migration/migration.types.js";
+/**
+ * Defines a database seed operation.
+ */
+export interface Seed {
+    /**
+     * Unique seed name.
+     */
+    readonly name: string;
+    /**
+     * Seed execution order. Seeds with equal order run in declaration order.
+     */
+    readonly order?: number;
+    /**
+     * Executes the seed.
+     */
+    readonly run: (database: DatabaseTransactionContext) => Promise<void>;
+    /**
+     * Optional cleanup operation.
+     */
+    readonly rollback?: (database: DatabaseTransactionContext) => Promise<void>;
+}
+/**
+ * Persisted seed execution record.
+ */
+export interface SeedRecord {
+    readonly name: string;
+    readonly appliedAt: Date;
+    /**
+     * Execution sequence number. Rollbacks walk this in descending order so
+     * seeds applied together in one batch are reverted in reverse execution
+     * order rather than alphabetically.
+     */
+    readonly sequence: number;
+}
+/**
+ * Result returned by the seed runner.
+ */
+export interface SeedResult {
+    readonly applied: readonly SeedRecord[];
+    readonly skipped: readonly SeedRecord[];
+}
+/**
+ * Seed runner status.
+ */
+export interface SeedStatus {
+    readonly pending: readonly Seed[];
+    readonly applied: readonly SeedRecord[];
+}
+/**
+ * Seed runner configuration (PostgreSQL only).
+ */
+export interface SeedRunnerOptions {
+    /**
+     * 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.
+     */
+    readonly transaction?: RunnerTransactionOptions;
+    /**
+     * When `true` (default) each seed runs in its own transaction; when
+     * `false` a whole batch runs in one all-or-nothing transaction. Applied
+     * history is always re-read under the advisory lock.
+     */
+    readonly perItemTransaction?: boolean;
+}
+/**
+ * Default seed tracking table.
+ */
+export declare const DEFAULT_SEED_TABLE = "_seeds";
+/**
+ * Default seed advisory lock.
+ */
+export declare 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 declare class SeedRunner {
+    private readonly client;
+    private readonly seeds;
+    private readonly tableName;
+    private readonly lockKey;
+    private readonly dialect;
+    private readonly transactionOptions;
+    private readonly perItemTransaction;
+    constructor(client: DatabaseClient, seeds: readonly Seed[], options?: SeedRunnerOptions);
+    /**
+     * Returns the seed runner status.
+     */
+    status(): Promise<SeedStatus>;
+    /**
+     * Executes every pending seed in order.
+     */
+    run(): Promise<SeedResult>;
+    /**
+     * Executes one named seed. Returns the existing record when already
+     * applied.
+     */
+    runOne(name: string): Promise<SeedRecord>;
+    /**
+     * Rolls back the most recently applied seed.
+     */
+    rollback(): Promise<SeedRecord | null>;
+    /**
+     * Rolls back every applied seed in reverse execution order.
+     */
+    rollbackAll(): Promise<readonly SeedRecord[]>;
+    /**
+     * Creates the seed tracking table if it does not exist, adding the
+     * `sequence` column to tables created by earlier versions.
+     */
+    ensureSeedTable(): Promise<void>;
+    /**
+     * Returns all applied seeds ordered by execution sequence.
+     */
+    getAppliedSeeds(transaction?: DatabaseTransactionContext): Promise<readonly SeedRecord[]>;
+    /**
+     * Alias of {@link getAppliedSeeds}.
+     */
+    getHistory(): Promise<readonly SeedRecord[]>;
+    private rollbackSteps;
+    private revertRecord;
+    private computePending;
+    private buildTransactionOptions;
+    private executor;
+    private executeSeed;
+    private recordSeed;
+    private deleteSeedRecord;
+    private acquireSeedLock;
+    private seedError;
+}
+/**
+ * Creates a seed runner.
+ */
+export declare function createSeedRunner(client: DatabaseClient, seeds: readonly Seed[], options?: SeedRunnerOptions): SeedRunner;
+/**
+ * Validates and sorts seed definitions (stable sort on `order`).
+ */
+export declare function normalizeSeeds(seeds: readonly Seed[]): readonly Seed[];
+/**
+ * Validates one seed definition.
+ */
+export declare function validateSeed(seed: Seed): void;
+//# sourceMappingURL=seed.runner.d.ts.map