@zudojs/database 0.0.1 → 1.0.0

package/dist/relations/relations.definition.js

@@ -0,0 +1,362 @@
+/**
+ * Default maximum include depth.
+ */
+export const DEFAULT_INCLUDE_DEPTH = 5;
+/**
+ * Creates a one-to-one relation definition.
+ */
+export function oneToOne(definition) {
+    const relation = Object.freeze({
+        ...definition,
+        type: "one-to-one",
+    });
+    validateRelation(relation);
+    return relation;
+}
+/**
+ * Creates a one-to-many relation definition.
+ */
+export function oneToMany(definition) {
+    const relation = Object.freeze({
+        ...definition,
+        type: "one-to-many",
+    });
+    validateRelation(relation);
+    return relation;
+}
+/**
+ * Creates a many-to-one relation definition.
+ */
+export function manyToOne(definition) {
+    const relation = Object.freeze({
+        ...definition,
+        type: "many-to-one",
+    });
+    validateRelation(relation);
+    return relation;
+}
+/**
+ * Creates a many-to-many relation definition.
+ */
+export function manyToMany(definition) {
+    const relation = Object.freeze({
+        ...definition,
+        type: "many-to-many",
+    });
+    validateRelation(relation);
+    return relation;
+}
+/**
+ * Creates a relation include definition.
+ */
+export function includeRelation(relation, options = {}) {
+    validateRelationName(relation);
+    if (options.select !== undefined) {
+        for (const field of options.select) {
+            validateFieldName(field);
+        }
+    }
+    if (options.include !== undefined) {
+        for (const nested of options.include) {
+            validateInclude(nested);
+        }
+    }
+    return Object.freeze({
+        relation,
+        select: options.select
+            ? Object.freeze([...new Set(options.select)])
+            : undefined,
+        include: options.include ? Object.freeze([...options.include]) : undefined,
+    });
+}
+/**
+ * Validates a relation include (recursively).
+ */
+export function validateInclude(include) {
+    if (!include || typeof include !== "object") {
+        throw new TypeError("A relation include is required.");
+    }
+    validateRelationName(include.relation);
+    for (const field of include.select ?? []) {
+        validateFieldName(field);
+    }
+    for (const nested of include.include ?? []) {
+        validateInclude(nested);
+    }
+}
+/**
+ * Translates relation includes into a Prisma `include` object.
+ *
+ * When a registry is supplied every relation is validated against the
+ * parent model (descending through child models for nested includes) and
+ * cyclic includes are rejected. Depth is bounded in all cases.
+ */
+export function toPrismaInclude(includes, options = {}) {
+    const maxDepth = options.depth ?? DEFAULT_INCLUDE_DEPTH;
+    if (!Number.isInteger(maxDepth) || maxDepth < 1) {
+        throw new TypeError("Include depth must be a positive integer.");
+    }
+    if (options.registry && options.parent === undefined) {
+        throw new TypeError("toPrismaInclude requires `parent` when a registry is supplied.");
+    }
+    return buildInclude(includes, options, options.parent, 1, maxDepth, []);
+}
+function buildInclude(includes, options, parent, depth, maxDepth, path) {
+    if (depth > maxDepth) {
+        throw new RangeError(`Relation include depth exceeds the maximum of ${maxDepth}.`);
+    }
+    const result = {};
+    for (const include of includes) {
+        validateInclude(include);
+        if (include.relation in result) {
+            throw new TypeError(`Relation "${include.relation}" is included more than once.`);
+        }
+        let definition;
+        if (options.registry) {
+            definition = options.registry.get(include.relation, parent);
+            if (!definition) {
+                throw new TypeError(`Relation "${include.relation}" is not registered for the parent model.`);
+            }
+            if (path.includes(definition)) {
+                throw new TypeError(`Relation include "${include.relation}" is cyclic.`);
+            }
+        }
+        const entry = {};
+        if (include.select && include.select.length > 0) {
+            const select = {};
+            for (const field of include.select) {
+                select[field] = true;
+            }
+            entry["select"] = select;
+        }
+        if (include.include && include.include.length > 0) {
+            const nested = buildInclude(include.include, options, definition ? definition.child : undefined, depth + 1, maxDepth, definition ? [...path, definition] : path);
+            if (entry["select"]) {
+                entry["select"] = { ...entry["select"], ...nested };
+            }
+            else {
+                entry["include"] = nested;
+            }
+        }
+        if (options.includeDeleted === false &&
+            definition &&
+            isCollectionRelation(definition)) {
+            const field = options.softDeleteField ?? "deletedAt";
+            validateFieldName(field);
+            entry["where"] = { [field]: null };
+        }
+        result[include.relation] = Object.keys(entry).length === 0 ? true : entry;
+    }
+    return result;
+}
+/**
+ * Creates a nested relation include.
+ */
+export function includeRelations(...includes) {
+    return Object.freeze([...includes]);
+}
+/**
+ * Relation registry used by database infrastructure.
+ *
+ * Relations are keyed by parent model and name, so two models may each
+ * define a relation with the same name.
+ */
+export class RelationRegistry {
+    relations = new Map();
+    /**
+     * Registers a relation.
+     */
+    register(relation) {
+        validateRelation(relation);
+        const byName = this.relations.get(relation.parent);
+        if (byName?.has(relation.name)) {
+            throw new Error(`Relation "${relation.name}" is already registered for this parent.`);
+        }
+        const frozen = Object.freeze({
+            ...relation,
+        });
+        if (byName) {
+            byName.set(relation.name, frozen);
+        }
+        else {
+            this.relations.set(relation.parent, new Map([[relation.name, frozen]]));
+        }
+        return this;
+    }
+    /**
+     * Registers multiple relations.
+     */
+    registerMany(relations) {
+        for (const relation of relations) {
+            this.register(relation);
+        }
+        return this;
+    }
+    /**
+     * Gets a relation by name.
+     *
+     * Without `parent` the name must be unique across all parents; an
+     * ambiguous lookup throws.
+     */
+    get(name, parent) {
+        if (parent !== undefined) {
+            return this.relations.get(parent)?.get(name);
+        }
+        const matches = this.findByName(name);
+        if (matches.length > 1) {
+            throw new Error(`Relation "${name}" is registered for multiple parents; specify the parent.`);
+        }
+        return matches[0];
+    }
+    /**
+     * Checks whether a relation exists.
+     */
+    has(name, parent) {
+        if (parent !== undefined) {
+            return this.relations.get(parent)?.has(name) ?? false;
+        }
+        return this.findByName(name).length > 0;
+    }
+    /**
+     * Removes a relation. Without `parent`, every relation with that name is
+     * removed.
+     */
+    remove(name, parent) {
+        if (parent !== undefined) {
+            const byName = this.relations.get(parent);
+            const removed = byName?.delete(name) ?? false;
+            if (byName && byName.size === 0) {
+                this.relations.delete(parent);
+            }
+            return removed;
+        }
+        let removed = false;
+        for (const [key, byName] of this.relations) {
+            if (byName.delete(name)) {
+                removed = true;
+            }
+            if (byName.size === 0) {
+                this.relations.delete(key);
+            }
+        }
+        return removed;
+    }
+    /**
+     * Returns all registered relations.
+     */
+    all() {
+        return Object.freeze([...this.relations.values()].flatMap((byName) => [...byName.values()]));
+    }
+    /**
+     * Returns relations for a specific parent entity.
+     */
+    forParent(parent) {
+        return Object.freeze([...(this.relations.get(parent)?.values() ?? [])]);
+    }
+    /**
+     * Returns relations for a specific child entity.
+     */
+    forChild(child) {
+        return Object.freeze(this.all().filter((relation) => relation.child === child));
+    }
+    /**
+     * Clears all registered relations.
+     */
+    clear() {
+        this.relations.clear();
+    }
+    /**
+     * Returns the number of registered relations.
+     */
+    get size() {
+        let size = 0;
+        for (const byName of this.relations.values()) {
+            size += byName.size;
+        }
+        return size;
+    }
+    findByName(name) {
+        const matches = [];
+        for (const byName of this.relations.values()) {
+            const relation = byName.get(name);
+            if (relation) {
+                matches.push(relation);
+            }
+        }
+        return matches;
+    }
+}
+/**
+ * Creates a relation registry.
+ */
+export function createRelationRegistry(relations = []) {
+    const registry = new RelationRegistry();
+    registry.registerMany(relations);
+    return registry;
+}
+/**
+ * Validates a relation definition.
+ */
+export function validateRelation(relation) {
+    if (!relation || typeof relation !== "object") {
+        throw new TypeError("A relation definition is required.");
+    }
+    validateRelationName(relation.name);
+    if (relation.parent === undefined || relation.parent === null) {
+        throw new TypeError(`Relation "${relation.name}" requires a parent entity.`);
+    }
+    if (relation.child === undefined || relation.child === null) {
+        throw new TypeError(`Relation "${relation.name}" requires a child entity.`);
+    }
+    if (!isRelationType(relation.type)) {
+        throw new TypeError(`Relation "${relation.name}" has an invalid relation type.`);
+    }
+    if (typeof relation.foreignKey !== "string" ||
+        relation.foreignKey.trim().length === 0) {
+        throw new TypeError(`Relation "${relation.name}" requires a foreign key.`);
+    }
+    if (typeof relation.referencedKey !== "string" ||
+        relation.referencedKey.trim().length === 0) {
+        throw new TypeError(`Relation "${relation.name}" requires a referenced key.`);
+    }
+}
+/**
+ * Checks whether a value is a supported relation type.
+ */
+export function isRelationType(value) {
+    return (value === "one-to-one" ||
+        value === "one-to-many" ||
+        value === "many-to-one" ||
+        value === "many-to-many");
+}
+/**
+ * Returns whether the relation represents a collection.
+ */
+export function isCollectionRelation(relation) {
+    return relation.type === "one-to-many" || relation.type === "many-to-many";
+}
+/**
+ * Returns whether the relation represents a single entity.
+ */
+export function isSingleRelation(relation) {
+    return relation.type === "one-to-one" || relation.type === "many-to-one";
+}
+/**
+ * Validates a relation name.
+ */
+function validateRelationName(name) {
+    if (typeof name !== "string" || name.trim().length === 0) {
+        throw new TypeError("A relation name is required.");
+    }
+    validateFieldName(name);
+}
+const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Validates a relation or select field name.
+ */
+function validateFieldName(field) {
+    if (typeof field !== "string" || !FIELD_PATTERN.test(field)) {
+        throw new TypeError(`Invalid relation field name "${String(field)}".`);
+    }
+}
+//# sourceMappingURL=relations.definition.js.map

package/dist/repository/index.d.ts

@@ -3,5 +3,6 @@
  *
  * Generic repository pattern with Prisma delegate support.
  */
-export { BaseRepository, type RepositoryDelegate, type BaseRepositoryOptions, } from "./repository.base.js";
+export { BaseRepository, type RepositoryDelegate, type BaseRepositoryOptions, type SoftDeleteOptions, type CursorQueryOptions, type TransactionClientLike, } from "./repository.base.js";
+export { mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, toErrorMetadata, createAbortError, createTimeoutError, type RepositoryOperation, type RepositoryErrorContext, type PrismaErrorLike, } from "./repository.errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/repository/index.js

@@ -4,4 +4,5 @@
  * Generic repository pattern with Prisma delegate support.
  */
 export { BaseRepository, } from "./repository.base.js";
+export { mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, toErrorMetadata, createAbortError, createTimeoutError, } from "./repository.errors.js";
 //# sourceMappingURL=index.js.map

package/dist/repository/repository.base.d.ts

@@ -0,0 +1,270 @@
+import type { DatabaseOperationOptions, PaginatedResult, QueryOptions, Repository, SoftDeletableRepository, SortInput } from "../databaseType/databaseType.type.js";
+import { type CursorPaginatedResult } from "../pagination/pagination.core.js";
+import type { QueryBuilder } from "../queryBuilder/queryBuilder.core.js";
+import type { QueryBuilderState } from "../queryBuilder/queryBuilder.type.js";
+import type { RelationLoadOptions, RelationRegistry } from "../relations/relations.definition.js";
+import { type RepositoryOperation } from "./repository.errors.js";
+/**
+ * Generic Prisma-style delegate contract.
+ *
+ * This keeps the repository base class independent from generated
+ * Prisma model types while still supporting standard CRUD operations.
+ */
+export interface RepositoryDelegate<TEntity, TId = string, TCreateInput = Partial<TEntity>, TUpdateInput = Partial<TEntity>, TWhereInput = unknown> {
+    findUnique(args: {
+        where: unknown;
+    }): Promise<TEntity | null>;
+    findFirst(args: {
+        where?: TWhereInput;
+        orderBy?: unknown;
+        select?: unknown;
+    }): Promise<TEntity | null>;
+    findMany(args?: {
+        where?: TWhereInput;
+        skip?: number;
+        take?: number;
+        orderBy?: unknown;
+        select?: unknown;
+        include?: unknown;
+    }): Promise<readonly TEntity[]>;
+    create(args: {
+        data: TCreateInput;
+    }): Promise<TEntity>;
+    update(args: {
+        where: unknown;
+        data: TUpdateInput;
+    }): Promise<TEntity>;
+    delete(args: {
+        where: unknown;
+    }): Promise<TEntity>;
+    count(args?: {
+        where?: TWhereInput;
+    }): Promise<number>;
+    upsert?(args: {
+        where: unknown;
+        create: TCreateInput;
+        update: TUpdateInput;
+    }): Promise<TEntity>;
+    createMany?(args: {
+        data: readonly TCreateInput[];
+    }): Promise<{
+        count: number;
+    }>;
+    deleteMany?(args: {
+        where?: TWhereInput;
+    }): Promise<{
+        count: number;
+    }>;
+}
+/**
+ * Soft-delete configuration.
+ */
+export interface SoftDeleteOptions {
+    /**
+     * Nullable timestamp column marking deleted rows (default `deletedAt`).
+     */
+    readonly field?: string;
+}
+/**
+ * Options for constructing a repository.
+ */
+export interface BaseRepositoryOptions {
+    readonly modelName?: string;
+    /**
+     * Primary key field used by `findById`, `update`, `delete` and friends
+     * (default `id`).
+     */
+    readonly idField?: string;
+    /**
+     * Enables soft deletion. Every read, count, exists, update and paginate
+     * path then excludes rows whose soft-delete field is set.
+     */
+    readonly softDelete?: boolean | SoftDeleteOptions;
+    /**
+     * Secret used to sign keyset cursors produced by `paginateCursor`.
+     */
+    readonly cursorSecret?: string;
+    /**
+     * Property on a transaction client that yields this model's delegate
+     * (default: `modelName` with a lower-cased first letter). Used by
+     * `withTransaction`.
+     */
+    readonly delegateKey?: string;
+    /**
+     * Relation registry used to validate `include` definitions passed to
+     * `findByQuery`.
+     */
+    readonly relations?: RelationRegistry;
+    /**
+     * Model identifier registered in `relations` for this repository's
+     * entity (default `modelName`).
+     */
+    readonly relationParent?: unknown;
+}
+/**
+ * Options for cursor pagination.
+ */
+export interface CursorQueryOptions<TField extends string = string> extends DatabaseOperationOptions {
+    readonly cursor?: string | null;
+    readonly limit?: number;
+    /**
+     * Sort order. The id field is appended as a tiebreaker when absent.
+     */
+    readonly sort?: readonly SortInput<TField>[];
+}
+/**
+ * A Prisma transaction client (or any object exposing model delegates).
+ */
+export type TransactionClientLike = Readonly<Record<string, unknown>>;
+/**
+ * Generic base repository implementation.
+ *
+ * Concrete repositories should extend this class and provide the
+ * appropriate Prisma delegate plus any domain-specific behavior.
+ */
+export declare abstract class BaseRepository<TEntity, TId = string, TCreateInput = Partial<TEntity>, TUpdateInput = Partial<TEntity>, TWhereInput = Record<string, unknown>> implements Repository<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput>, SoftDeletableRepository<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput> {
+    protected readonly delegate: RepositoryDelegate<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput>;
+    protected readonly modelName: string;
+    protected readonly idField: string;
+    protected readonly softDeleteField?: string;
+    protected readonly cursorSecret?: string;
+    protected readonly delegateKey: string;
+    protected readonly relations?: RelationRegistry;
+    protected readonly relationParent: unknown;
+    /**
+     * When true, soft-deleted rows are visible to reads (see `withDeleted`).
+     */
+    protected readonly includeDeleted: boolean;
+    constructor(delegate: RepositoryDelegate<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput>, options?: BaseRepositoryOptions);
+    /**
+     * Returns a copy of this repository bound to a transaction client's
+     * delegate, so operations run inside the transaction.
+     */
+    withTransaction(transaction: TransactionClientLike): this;
+    /**
+     * Returns a copy of this repository bound to a different delegate.
+     */
+    withDelegate(delegate: RepositoryDelegate<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput>): this;
+    /**
+     * Returns a copy of this repository whose reads include soft-deleted
+     * rows.
+     */
+    withDeleted(): this;
+    /**
+     * Finds an entity by its primary identifier.
+     */
+    findById(id: TId, options?: DatabaseOperationOptions): Promise<TEntity | null>;
+    /**
+     * Finds the first entity matching a filter.
+     */
+    findOne(filter: TWhereInput, options?: DatabaseOperationOptions): Promise<TEntity | null>;
+    /**
+     * Finds all entities matching a filter.
+     */
+    findMany(filter?: TWhereInput, options?: DatabaseOperationOptions): Promise<readonly TEntity[]>;
+    /**
+     * Finds entities using pagination and sorting.
+     */
+    findPaginated<TField extends string = string>(filter?: TWhereInput, options?: QueryOptions<TField>): Promise<PaginatedResult<TEntity>>;
+    /**
+     * Alias of {@link findPaginated}.
+     */
+    paginate<TField extends string = string>(filter?: TWhereInput, options?: QueryOptions<TField>): Promise<PaginatedResult<TEntity>>;
+    /**
+     * 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.
+     */
+    paginateCursor<TField extends string = string>(filter?: TWhereInput, options?: CursorQueryOptions<TField>): Promise<CursorPaginatedResult<TEntity>>;
+    /**
+     * 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.
+     */
+    findByQuery<TField extends string = string>(query: QueryBuilder<TField> | QueryBuilderState<TField>, options?: RelationLoadOptions): Promise<readonly TEntity[]>;
+    /**
+     * Creates a new entity.
+     */
+    create(input: TCreateInput, options?: DatabaseOperationOptions): Promise<TEntity>;
+    /**
+     * Creates many entities and returns the number created.
+     */
+    createMany(inputs: readonly TCreateInput[], options?: DatabaseOperationOptions): Promise<number>;
+    /**
+     * Updates an entity by its identifier.
+     */
+    update(id: TId, input: TUpdateInput, options?: DatabaseOperationOptions): Promise<TEntity>;
+    /**
+     * Deletes an entity by its identifier (hard delete).
+     */
+    delete(id: TId, options?: DatabaseOperationOptions): Promise<void>;
+    /**
+     * Deletes every entity matching a filter (hard delete, including
+     * soft-deleted rows) and returns the number removed.
+     */
+    deleteMany(filter: TWhereInput, options?: DatabaseOperationOptions): Promise<number>;
+    /**
+     * Marks an entity as deleted by setting its soft-delete field.
+     */
+    softDelete(id: TId, options?: DatabaseOperationOptions): Promise<TEntity>;
+    /**
+     * Restores a soft-deleted entity.
+     */
+    restore(id: TId, options?: DatabaseOperationOptions): Promise<TEntity>;
+    /**
+     * Finds soft-deleted entities matching a filter.
+     */
+    findDeleted(filter?: TWhereInput, options?: DatabaseOperationOptions): Promise<readonly TEntity[]>;
+    /**
+     * Checks whether an entity exists.
+     */
+    exists(filter: TWhereInput, options?: DatabaseOperationOptions): Promise<boolean>;
+    /**
+     * Counts entities matching a filter.
+     */
+    count(filter?: TWhereInput, options?: DatabaseOperationOptions): Promise<number>;
+    /**
+     * Updates an entity if it exists, otherwise creates it.
+     */
+    upsert(where: TWhereInput, create: TCreateInput, update: TUpdateInput, options?: DatabaseOperationOptions): Promise<TEntity>;
+    /**
+     * 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).
+     */
+    protected execute<TResult>(operation: RepositoryOperation | string, callback: () => Promise<TResult>, options?: DatabaseOperationOptions): Promise<TResult>;
+    /**
+     * Validates an entity identifier.
+     */
+    protected validateId(id: TId): void;
+    /**
+     * Validates a repository filter.
+     */
+    protected validateFilter(filter: TWhereInput): void;
+    /**
+     * Builds the primary-key `where` for an identifier.
+     */
+    protected whereId(id: TId): Record<string, unknown>;
+    /**
+     * Applies the soft-delete scope to a filter when enabled.
+     */
+    protected scope(filter?: TWhereInput): TWhereInput | undefined;
+    /**
+     * Converts generic sort definitions into Prisma-compatible orderBy.
+     */
+    protected buildOrderBy<TField extends string>(sort?: readonly SortInput<TField>[]): ReadonlyArray<Record<string, string>> | undefined;
+    private isScoped;
+    private requireSoftDelete;
+    private buildCursorSort;
+    private rebind;
+}
+//# sourceMappingURL=repository.base.d.ts.map