@zudojs/database 0.1.0 → 1.1.0

package/dist/repository/repository.base.js

@@ -1,4 +1,10 @@
 import { DatabaseError } from "@zudojs/errors";
+import { createPaginationMeta, normalizeLimit, normalizePage, } from "../pagination/pagination.core.js";
+import { buildKeysetWhere, createKeysetPage, decodeKeysetCursor, } from "../pagination/pagination.keyset.js";
+import { toPrismaArgs, toPrismaOrderBy, } from "../queryBuilder/queryBuilder.prisma.js";
+import { createAbortError, createTimeoutError, mapRepositoryError, } from "./repository.errors.js";
+const DEFAULT_SOFT_DELETE_FIELD = "deletedAt";
+const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
  * Generic base repository implementation.
  *
@@ -8,23 +14,82 @@ import { DatabaseError } from "@zudojs/errors";
 export class BaseRepository {
     delegate;
     modelName;
+    idField;
+    softDeleteField;
+    cursorSecret;
+    delegateKey;
+    relations;
+    relationParent;
+    /**
+     * When true, soft-deleted rows are visible to reads (see `withDeleted`).
+     */
+    includeDeleted = false;
     constructor(delegate, options = {}) {
         if (!delegate) {
             throw new TypeError("A repository delegate is required.");
         }
         this.delegate = delegate;
         this.modelName = options.modelName ?? "DatabaseEntity";
+        this.idField = validateFieldName(options.idField ?? "id", "idField");
+        if (options.softDelete) {
+            const field = typeof options.softDelete === "object"
+                ? (options.softDelete.field ?? DEFAULT_SOFT_DELETE_FIELD)
+                : DEFAULT_SOFT_DELETE_FIELD;
+            this.softDeleteField = validateFieldName(field, "softDelete.field");
+        }
+        if (options.cursorSecret !== undefined) {
+            if (typeof options.cursorSecret !== "string" ||
+                options.cursorSecret.length === 0) {
+                throw new TypeError("cursorSecret must be a non-empty string.");
+            }
+            this.cursorSecret = options.cursorSecret;
+        }
+        this.delegateKey = validateFieldName(options.delegateKey ?? lowerFirst(this.modelName), "delegateKey");
+        this.relations = options.relations;
+        this.relationParent = options.relationParent ?? this.modelName;
+    }
+    /**
+     * Returns a copy of this repository bound to a transaction client's
+     * delegate, so operations run inside the transaction.
+     */
+    withTransaction(transaction) {
+        if (transaction === null || typeof transaction !== "object") {
+            throw new TypeError("A transaction client is required.");
+        }
+        const delegate = transaction[this.delegateKey];
+        if (!delegate || typeof delegate !== "object") {
+            throw new DatabaseError(`Transaction client has no "${this.delegateKey}" delegate for ${this.modelName}.`);
+        }
+        return this.withDelegate(delegate);
+    }
+    /**
+     * Returns a copy of this repository bound to a different delegate.
+     */
+    withDelegate(delegate) {
+        if (!delegate) {
+            throw new TypeError("A repository delegate is required.");
+        }
+        return this.rebind({ delegate });
+    }
+    /**
+     * Returns a copy of this repository whose reads include soft-deleted
+     * rows.
+     */
+    withDeleted() {
+        return this.rebind({ includeDeleted: true });
     }
     /**
      * Finds an entity by its primary identifier.
      */
     async findById(id, options) {
         this.validateId(id);
-        return this.execute("findById", () => this.delegate.findUnique({
-            where: {
-                id,
-            },
-        }), options);
+        return this.execute("findById", () => this.isScoped()
+            ? this.delegate.findFirst({
+                where: this.scope(this.whereId(id)),
+            })
+            : this.delegate.findUnique({
+                where: this.whereId(id),
+            }), options);
     }
     /**
      * Finds the first entity matching a filter.
@@ -32,7 +97,7 @@ export class BaseRepository {
     async findOne(filter, options) {
         this.validateFilter(filter);
         return this.execute("findOne", () => this.delegate.findFirst({
-            where: filter,
+            where: this.scope(filter),
         }), options);
     }
     /**
@@ -43,7 +108,7 @@ export class BaseRepository {
             this.validateFilter(filter);
         }
         return this.execute("findMany", () => this.delegate.findMany({
-            where: filter,
+            where: this.scope(filter),
         }), options);
     }
     /**
@@ -53,16 +118,18 @@ export class BaseRepository {
         if (filter !== undefined) {
             this.validateFilter(filter);
         }
-        const pagination = options?.pagination;
-        const page = normalizePage(pagination);
-        const limit = normalizeLimit(pagination);
+        const page = normalizePage(options?.pagination?.page);
+        const limit = normalizeLimit(options?.pagination?.limit);
         const skip = (page - 1) * limit;
+        // Validated before either query is dispatched, so an invalid sort never
+        // costs a `count` round-trip.
+        const orderBy = this.buildOrderBy(options?.sort);
         const [data, total] = await Promise.all([
-            this.execute("findMany", () => this.delegate.findMany({
-                where: filter,
+            this.execute("findPaginated", () => this.delegate.findMany({
+                where: this.scope(filter),
                 skip,
                 take: limit,
-                orderBy: this.buildOrderBy(options?.sort),
+                orderBy,
             }), options),
             this.count(filter, options),
         ]);
@@ -71,6 +138,83 @@ export class BaseRepository {
             meta: createPaginationMeta(page, limit, total),
         };
     }
+    /**
+     * Alias of {@link findPaginated}.
+     */
+    async paginate(filter, options) {
+        return this.findPaginated(filter, options);
+    }
+    /**
+     * Finds entities using keyset (cursor) pagination.
+     *
+     * Rows are ordered by `options.sort` (the id field is appended as a
+     * tiebreaker), `limit + 1` rows are fetched and the extra row decides
+     * `hasNextPage`. Cursors are validated against the sort fields and, when
+     * `cursorSecret` is configured, signed.
+     */
+    async paginateCursor(filter, options) {
+        if (filter !== undefined) {
+            this.validateFilter(filter);
+        }
+        const sort = this.buildCursorSort(options?.sort);
+        const orderBy = this.buildOrderBy(sort);
+        const limit = normalizeLimit(options?.limit);
+        const cursor = options?.cursor ?? null;
+        let where = this.scope(filter);
+        if (cursor !== null) {
+            const payload = decodeKeysetCursor(cursor, sort, this.cursorSecret);
+            const keyset = buildKeysetWhere(payload, sort);
+            where = where === undefined ? keyset : { AND: [where, keyset] };
+        }
+        const rows = await this.execute("paginateCursor", () => this.delegate.findMany({
+            where: where,
+            take: limit + 1,
+            orderBy,
+        }), options);
+        return createKeysetPage(rows, {
+            sort,
+            limit,
+            cursor,
+            secret: this.cursorSecret,
+        });
+    }
+    /**
+     * Finds entities from a query builder (or its built state), applying the
+     * filter, sort, select, include and pagination it carries.
+     *
+     * `options.includeDeleted` and `options.depth` control how relation
+     * includes are resolved (see `toPrismaInclude`); by default soft-deleted
+     * rows of collection relations are filtered whenever this repository
+     * filters its own rows.
+     */
+    async findByQuery(query, options) {
+        const state = isQueryBuilder(query) ? query.build() : query;
+        if (!state || typeof state !== "object") {
+            throw new DatabaseError(`${this.modelName} query is required.`);
+        }
+        const includeDeleted = options?.includeDeleted ?? (this.includeDeleted || !this.softDeleteField);
+        const includeOptions = this.relations
+            ? {
+                registry: this.relations,
+                parent: this.relationParent,
+                includeDeleted,
+                softDeleteField: this.softDeleteField,
+                ...(options?.depth !== undefined ? { depth: options.depth } : {}),
+            }
+            : options?.depth !== undefined
+                ? { depth: options.depth }
+                : undefined;
+        const args = toPrismaArgs(state, { include: includeOptions });
+        const where = this.scope(args.where);
+        return this.execute("findByQuery", () => this.delegate.findMany({
+            where,
+            skip: args.skip,
+            take: args.take,
+            orderBy: args.orderBy,
+            select: args.select,
+            include: args.include,
+        }), options);
+    }
     /**
      * Creates a new entity.
      */
@@ -82,6 +226,26 @@ export class BaseRepository {
             data: input,
         }), options);
     }
+    /**
+     * Creates many entities and returns the number created.
+     */
+    async createMany(inputs, options) {
+        if (!Array.isArray(inputs)) {
+            throw new DatabaseError(`Cannot create ${this.modelName}: inputs must be an array.`);
+        }
+        if (inputs.some((input) => input === undefined || input === null)) {
+            throw new DatabaseError(`Cannot create ${this.modelName}: every input is required.`);
+        }
+        if (inputs.length === 0) {
+            return 0;
+        }
+        const createMany = this.delegate.createMany;
+        if (typeof createMany !== "function") {
+            throw new DatabaseError(`createMany is not supported by ${this.modelName}.`);
+        }
+        const result = await this.execute("createMany", () => createMany.call(this.delegate, { data: inputs }), options);
+        return result.count;
+    }
     /**
      * Updates an entity by its identifier.
      */
@@ -91,21 +255,67 @@ export class BaseRepository {
             throw new DatabaseError(`Cannot update ${this.modelName}: input is required.`);
         }
         return this.execute("update", () => this.delegate.update({
-            where: {
-                id,
-            },
+            where: this.whereUniqueId(id),
             data: input,
         }), options);
     }
     /**
-     * Deletes an entity by its identifier.
+     * Deletes an entity by its identifier (hard delete).
      */
     async delete(id, options) {
         this.validateId(id);
         await this.execute("delete", () => this.delegate.delete({
-            where: {
-                id,
-            },
+            where: this.whereId(id),
+        }), options);
+    }
+    /**
+     * Deletes every entity matching a filter (hard delete, including
+     * soft-deleted rows) and returns the number removed.
+     */
+    async deleteMany(filter, options) {
+        this.validateFilter(filter);
+        const deleteMany = this.delegate.deleteMany;
+        if (typeof deleteMany !== "function") {
+            throw new DatabaseError(`deleteMany is not supported by ${this.modelName}.`);
+        }
+        const result = await this.execute("deleteMany", () => deleteMany.call(this.delegate, { where: filter }), options);
+        return result.count;
+    }
+    /**
+     * Marks an entity as deleted by setting its soft-delete field.
+     */
+    async softDelete(id, options) {
+        const field = this.requireSoftDelete("softDelete");
+        this.validateId(id);
+        return this.execute("softDelete", () => this.delegate.update({
+            where: { ...this.whereId(id), [field]: null },
+            data: { [field]: new Date() },
+        }), options);
+    }
+    /**
+     * Restores a soft-deleted entity.
+     */
+    async restore(id, options) {
+        const field = this.requireSoftDelete("restore");
+        this.validateId(id);
+        return this.execute("restore", () => this.delegate.update({
+            where: { ...this.whereId(id), [field]: { not: null } },
+            data: { [field]: null },
+        }), options);
+    }
+    /**
+     * Finds soft-deleted entities matching a filter.
+     */
+    async findDeleted(filter, options) {
+        const field = this.requireSoftDelete("findDeleted");
+        if (filter !== undefined) {
+            this.validateFilter(filter);
+        }
+        const deleted = { [field]: { not: null } };
+        return this.execute("findDeleted", () => this.delegate.findMany({
+            where: (filter === undefined
+                ? deleted
+                : { AND: [filter, deleted] }),
         }), options);
     }
     /**
@@ -113,10 +323,10 @@ export class BaseRepository {
      */
     async exists(filter, options) {
         this.validateFilter(filter);
-        const entity = await this.execute("exists", () => this.delegate.findFirst({
-            where: filter,
+        const total = await this.execute("exists", () => this.delegate.count({
+            where: this.scope(filter),
         }), options);
-        return entity !== null;
+        return total > 0;
     }
     /**
      * Counts entities matching a filter.
@@ -126,17 +336,25 @@ export class BaseRepository {
             this.validateFilter(filter);
         }
         return this.execute("count", () => this.delegate.count({
-            where: filter,
+            where: this.scope(filter),
         }), options);
     }
     /**
      * Updates an entity if it exists, otherwise creates it.
      */
     async upsert(where, create, update, options) {
-        if (typeof this.delegate.upsert !== "function") {
+        this.validateFilter(where);
+        if (create === undefined || create === null) {
+            throw new DatabaseError(`Cannot upsert ${this.modelName}: create input is required.`);
+        }
+        if (update === undefined || update === null) {
+            throw new DatabaseError(`Cannot upsert ${this.modelName}: update input is required.`);
+        }
+        const upsert = this.delegate.upsert;
+        if (typeof upsert !== "function") {
             throw new DatabaseError(`Upsert is not supported by ${this.modelName}.`);
         }
-        return this.execute("upsert", () => this.delegate.upsert({
+        return this.execute("upsert", () => upsert.call(this.delegate, {
             where,
             create,
             update,
@@ -144,35 +362,64 @@ export class BaseRepository {
     }
     /**
      * Executes a repository operation and normalizes database failures.
+     *
+     * Honours `options.signal` for the whole duration of the call and
+     * `options.timeoutMs` as a client-side deadline (the underlying query is
+     * not cancelled server-side).
      */
     async execute(operation, callback, options) {
-        if (options?.signal?.aborted) {
-            throw new DatabaseError(`${this.modelName} ${operation} was aborted.`);
+        const context = {
+            model: this.modelName,
+            operation,
+            metadata: options?.metadata,
+        };
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            throw createAbortError(context, signal.reason);
         }
         const startedAt = Date.now();
+        let timer;
+        let onAbort;
+        const guards = [];
+        if (signal) {
+            guards.push(new Promise((_, reject) => {
+                onAbort = () => reject(createAbortError(context, signal.reason));
+                signal.addEventListener("abort", onAbort, { once: true });
+            }));
+        }
+        if (options?.timeoutMs !== undefined) {
+            if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+                throw new DatabaseError(`${this.modelName} ${operation}: timeoutMs must be a positive number.`);
+            }
+            const timeoutMs = options.timeoutMs;
+            guards.push(new Promise((_, reject) => {
+                timer = setTimeout(() => reject(createTimeoutError(context, timeoutMs)), timeoutMs);
+            }));
+        }
         try {
-            const promise = callback();
-            if (options?.timeoutMs && options.timeoutMs > 0) {
-                return await withTimeout(promise, options.timeoutMs, `${this.modelName} ${operation} timed out.`);
+            const promise = Promise.resolve().then(callback);
+            if (guards.length === 0) {
+                return await promise;
             }
-            return await promise;
+            // Keep a handler on the operation so a late rejection after a
+            // timeout/abort does not surface as an unhandled rejection.
+            promise.catch(() => undefined);
+            return await Promise.race([promise, ...guards]);
         }
         catch (error) {
-            if (error instanceof DatabaseError) {
-                throw error;
-            }
-            throw new DatabaseError(error instanceof Error
-                ? error.message
-                : `${this.modelName} ${operation} failed.`, {
-                cause: error,
-                metadata: {
-                    model: this.modelName,
-                    operation,
-                    durationMs: Date.now() - startedAt,
-                    ...(options?.metadata ?? {}),
-                },
+            throw mapRepositoryError(error, {
+                ...context,
+                durationMs: Date.now() - startedAt,
             });
         }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            if (signal && onAbort) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        }
     }
     /**
      * Validates an entity identifier.
@@ -180,7 +427,8 @@ export class BaseRepository {
     validateId(id) {
         if (id === undefined ||
             id === null ||
-            (typeof id === "string" && id.trim().length === 0)) {
+            (typeof id === "string" && id.trim().length === 0) ||
+            (typeof id === "number" && !Number.isFinite(id))) {
             throw new DatabaseError(`${this.modelName} identifier is required.`);
         }
     }
@@ -188,61 +436,94 @@ export class BaseRepository {
      * Validates a repository filter.
      */
     validateFilter(filter) {
-        if (filter === undefined || filter === null) {
+        if (filter === undefined ||
+            filter === null ||
+            typeof filter !== "object" ||
+            Array.isArray(filter)) {
             throw new DatabaseError(`${this.modelName} filter is required.`);
         }
     }
+    /**
+     * Builds the primary-key `where` for an identifier.
+     */
+    whereId(id) {
+        return { [this.idField]: id };
+    }
+    /**
+     * Builds the primary-key `where` for a *unique* operation (`update`),
+     * folding the soft-delete scope in as a sibling of the id rather than
+     * wrapping it in `AND`. Prisma's `WhereUniqueInput` requires the unique
+     * field at the top level, so `{ AND: [{ id }, { deletedAt: null }] }` is
+     * rejected with a validation error.
+     */
+    whereUniqueId(id) {
+        const where = this.whereId(id);
+        return this.isScoped() ? { ...where, [this.softDeleteField]: null } : where;
+    }
+    /**
+     * Applies the soft-delete scope to a filter when enabled.
+     */
+    scope(filter) {
+        if (!this.isScoped()) {
+            return filter;
+        }
+        const alive = { [this.softDeleteField]: null };
+        if (filter === undefined) {
+            return alive;
+        }
+        return { AND: [filter, alive] };
+    }
     /**
      * Converts generic sort definitions into Prisma-compatible orderBy.
+     *
+     * Field names and directions are validated the same way the query
+     * builder validates them (`toPrismaOrderBy`), so a sort taken from
+     * request input cannot reach the delegate with an arbitrary key or an
+     * unsupported direction.
      */
     buildOrderBy(sort) {
-        if (!sort || sort.length === 0) {
-            return undefined;
+        return toPrismaOrderBy(sort);
+    }
+    isScoped() {
+        return this.softDeleteField !== undefined && !this.includeDeleted;
+    }
+    requireSoftDelete(operation) {
+        if (!this.softDeleteField) {
+            throw new DatabaseError(`${this.modelName} ${operation} requires the softDelete option.`);
         }
-        return sort.map((entry) => ({
-            [entry.field]: entry.direction,
+        return this.softDeleteField;
+    }
+    buildCursorSort(sort) {
+        const result = (sort ?? []).map((entry) => ({
+            field: entry.field,
+            direction: entry.direction,
         }));
+        if (!result.some((entry) => entry.field === this.idField)) {
+            result.push({
+                field: this.idField,
+                direction: result[0]?.direction ?? "asc",
+            });
+        }
+        return result;
+    }
+    rebind(overrides) {
+        const copy = Object.create(Object.getPrototypeOf(this));
+        Object.assign(copy, this, overrides);
+        return copy;
     }
 }
-/**
- * Creates pagination metadata.
- */
-function createPaginationMeta(page, limit, total) {
-    const totalPages = total === 0 ? 0 : Math.ceil(total / limit);
-    return {
-        page,
-        limit,
-        total,
-        totalPages,
-        hasNextPage: totalPages > 0 && page < totalPages,
-        hasPreviousPage: page > 1 && totalPages > 0,
-    };
+function isQueryBuilder(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.build === "function");
 }
-/**
- * Normalizes a requested page number.
- */
-function normalizePage(input) {
-    return Math.max(1, Math.floor(input?.page ?? 1));
-}
-/**
- * Normalizes a requested page size.
- */
-function normalizeLimit(input) {
-    return Math.min(100, Math.max(1, Math.floor(input?.limit ?? 20)));
-}
-/**
- * Resolves an operation with a timeout.
- */
-async function withTimeout(promise, timeoutMs, message) {
-    let timer;
-    const timeout = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new DatabaseError(message)), timeoutMs);
-    });
-    try {
-        return await Promise.race([promise, timeout]);
-    }
-    finally {
-        clearTimeout(timer);
+function validateFieldName(field, name) {
+    if (typeof field !== "string" || !FIELD_PATTERN.test(field)) {
+        throw new TypeError(`Invalid ${name} "${String(field)}".`);
     }
+    return field;
+}
+function lowerFirst(value) {
+    return value.length === 0 ? value : value[0].toLowerCase() + value.slice(1);
 }
 //# sourceMappingURL=repository.base.js.map

package/dist/repository/repository.errors.d.ts

@@ -0,0 +1,60 @@
+import { DatabaseError, DatabaseOperation, type ErrorMetadata } from "@zudojs/errors";
+/**
+ * Repository operation names used for error diagnostics.
+ */
+export type RepositoryOperation = "findById" | "findOne" | "findMany" | "findPaginated" | "findByQuery" | "paginateCursor" | "findDeleted" | "count" | "exists" | "create" | "createMany" | "update" | "upsert" | "softDelete" | "restore" | "delete" | "deleteMany";
+/**
+ * Context attached to a mapped repository error.
+ */
+export interface RepositoryErrorContext {
+    readonly model: string;
+    readonly operation: RepositoryOperation | string;
+    readonly durationMs: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Shape of a Prisma known request error, detected structurally so the
+ * mapper does not depend on which `@prisma/client` copy raised it.
+ */
+export interface PrismaErrorLike {
+    readonly code: string;
+    readonly message: string;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly clientVersion?: string;
+}
+/**
+ * Determines whether a value looks like a Prisma known request error.
+ */
+export declare function isPrismaErrorLike(value: unknown): value is PrismaErrorLike;
+/**
+ * Maps a repository operation name to the errors package operation enum.
+ */
+export declare function toDatabaseOperation(operation: RepositoryOperation | string): DatabaseOperation;
+/**
+ * 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 declare function mapRepositoryError(error: unknown, context: RepositoryErrorContext): DatabaseError;
+/**
+ * Creates the error raised when an operation is aborted via `AbortSignal`.
+ */
+export declare function createAbortError(context: Omit<RepositoryErrorContext, "durationMs">, reason?: unknown): DatabaseError;
+/**
+ * Creates the error raised when a client-side timeout elapses.
+ */
+export declare function createTimeoutError(context: Omit<RepositoryErrorContext, "durationMs">, timeoutMs: number): DatabaseError;
+/**
+ * Converts arbitrary metadata into the serializable shape the errors
+ * package accepts.
+ */
+export declare function toErrorMetadata(value?: Readonly<Record<string, unknown>>): ErrorMetadata;
+//# sourceMappingURL=repository.errors.d.ts.map