@zudojs/database 0.1.0 → 1.1.0

package/dist/queryBuilder/queryBuilder.prisma.d.ts

@@ -0,0 +1,60 @@
+import type { PaginationInput, SortInput } from "../databaseType/databaseType.type.js";
+import { type ToPrismaIncludeOptions } from "../relations/relations.definition.js";
+import type { QueryBuilderState, QueryFilter } from "./queryBuilder.type.js";
+/**
+ * A Prisma-compatible `where` object.
+ */
+export type PrismaWhere = Record<string, unknown>;
+/**
+ * Prisma-compatible query arguments produced from a builder state.
+ */
+export interface PrismaQueryArgs {
+    readonly where?: PrismaWhere;
+    readonly orderBy?: readonly Record<string, "asc" | "desc">[];
+    readonly skip?: number;
+    readonly take?: number;
+    /**
+     * Field projection. When the state carries both `select` and `include`,
+     * the relations are folded in here (Prisma does not accept both keys on
+     * one level), so values may be nested include objects.
+     */
+    readonly select?: Record<string, boolean | Record<string, unknown>>;
+    readonly include?: Record<string, unknown>;
+}
+/**
+ * Options for {@link toPrismaArgs}.
+ */
+export interface ToPrismaArgsOptions {
+    /**
+     * Options forwarded to {@link toPrismaInclude} for `include` entries.
+     */
+    readonly include?: ToPrismaIncludeOptions;
+}
+/**
+ * Translates a database-neutral {@link QueryFilter} into a Prisma `where`
+ * object.
+ *
+ * Returns `undefined` when the filter carries no constraints. Unknown
+ * operators and unsafe field names throw a `TypeError`.
+ */
+export declare function toPrismaWhere(filter?: QueryFilter): PrismaWhere | undefined;
+/**
+ * Translates a builder state into Prisma `findMany`-style arguments.
+ */
+export declare function toPrismaArgs<TField extends string = string>(state: QueryBuilderState<TField>, options?: ToPrismaArgsOptions): PrismaQueryArgs;
+/**
+ * Translates sort definitions into Prisma `orderBy` entries.
+ */
+export declare function toPrismaOrderBy<TField extends string = string>(sort?: readonly SortInput<TField>[]): Record<string, "asc" | "desc">[] | undefined;
+/**
+ * Translates a field list into a Prisma `select` object.
+ */
+export declare function toPrismaSelect(fields: readonly string[]): Record<string, boolean>;
+/**
+ * Resolves pagination / offset into Prisma `skip` and `take`.
+ */
+export declare function toPrismaSkipTake(pagination?: PaginationInput, offset?: number): {
+    readonly skip?: number;
+    readonly take?: number;
+};
+//# sourceMappingURL=queryBuilder.prisma.d.ts.map

package/dist/queryBuilder/queryBuilder.prisma.js

@@ -0,0 +1,233 @@
+import { normalizePagination } from "../pagination/pagination.core.js";
+import { toPrismaInclude, } from "../relations/relations.definition.js";
+const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const FORBIDDEN_FIELDS = new Set(["__proto__", "constructor", "prototype"]);
+const SIMPLE_OPERATORS = new Set([
+    "equals",
+    "not",
+    "in",
+    "notIn",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "contains",
+    "startsWith",
+    "endsWith",
+]);
+const RELATION_OPERATORS = new Set([
+    "some",
+    "every",
+    "none",
+    "is",
+    "isNot",
+]);
+/**
+ * Translates a database-neutral {@link QueryFilter} into a Prisma `where`
+ * object.
+ *
+ * Returns `undefined` when the filter carries no constraints. Unknown
+ * operators and unsafe field names throw a `TypeError`.
+ */
+export function toPrismaWhere(filter) {
+    if (!filter || typeof filter !== "object") {
+        return undefined;
+    }
+    const where = {};
+    const extraAnd = [];
+    for (const condition of filter.conditions ?? []) {
+        const entry = translateCondition(condition);
+        const fieldWhere = entry[condition.field];
+        const existing = where[condition.field];
+        if (existing === undefined) {
+            where[condition.field] = fieldWhere;
+            continue;
+        }
+        const [operatorKey] = Object.keys(fieldWhere);
+        if (isPlainObject(existing) &&
+            operatorKey !== undefined &&
+            !(operatorKey in existing)) {
+            where[condition.field] = { ...existing, ...fieldWhere };
+            continue;
+        }
+        extraAnd.push(entry);
+    }
+    const andChildren = [
+        ...(filter.and ?? []).map((child) => toPrismaWhere(child)),
+        ...extraAnd,
+    ].filter((child) => child !== undefined);
+    if (andChildren.length > 0) {
+        where["AND"] = andChildren;
+    }
+    const orChildren = (filter.or ?? [])
+        .map((child) => toPrismaWhere(child))
+        .filter((child) => child !== undefined);
+    if (orChildren.length > 0) {
+        where["OR"] = orChildren;
+    }
+    if (filter.not) {
+        const negated = toPrismaWhere(filter.not);
+        if (negated !== undefined) {
+            where["NOT"] = negated;
+        }
+    }
+    return Object.keys(where).length === 0 ? undefined : where;
+}
+/**
+ * Translates a builder state into Prisma `findMany`-style arguments.
+ */
+export function toPrismaArgs(state, options = {}) {
+    const args = {};
+    const where = toPrismaWhere(state.filter);
+    if (where !== undefined) {
+        args.where = where;
+    }
+    const orderBy = toPrismaOrderBy(state.sort);
+    if (orderBy !== undefined) {
+        args.orderBy = orderBy;
+    }
+    const { skip, take } = toPrismaSkipTake(state.pagination, state.offset);
+    if (skip !== undefined) {
+        args.skip = skip;
+    }
+    if (take !== undefined) {
+        args.take = take;
+    }
+    const select = state.select && state.select.length > 0
+        ? toPrismaSelect(state.select)
+        : undefined;
+    const include = state.include && state.include.length > 0
+        ? toPrismaInclude(state.include, options.include)
+        : undefined;
+    if (select !== undefined && include !== undefined) {
+        // Prisma rejects `select` and `include` on the same level; relations
+        // are folded into the projection instead.
+        args.select = {
+            ...select,
+            ...include,
+        };
+    }
+    else if (select !== undefined) {
+        args.select = select;
+    }
+    else if (include !== undefined) {
+        args.include = include;
+    }
+    return args;
+}
+/**
+ * Translates sort definitions into Prisma `orderBy` entries.
+ */
+export function toPrismaOrderBy(sort) {
+    if (!sort || sort.length === 0) {
+        return undefined;
+    }
+    return sort.map((entry) => {
+        validateFieldName(entry.field);
+        if (entry.direction !== "asc" && entry.direction !== "desc") {
+            throw new TypeError(`Sort field "${entry.field}" has an invalid direction.`);
+        }
+        return { [entry.field]: entry.direction };
+    });
+}
+/**
+ * Translates a field list into a Prisma `select` object.
+ */
+export function toPrismaSelect(fields) {
+    const select = {};
+    for (const field of fields) {
+        validateFieldName(field);
+        select[field] = true;
+    }
+    return select;
+}
+/**
+ * Resolves pagination / offset into Prisma `skip` and `take`.
+ */
+export function toPrismaSkipTake(pagination, offset) {
+    if (offset !== undefined) {
+        if (!Number.isFinite(offset) || offset < 0) {
+            throw new TypeError("Query offset must be a non-negative number.");
+        }
+        const take = pagination?.limit !== undefined
+            ? normalizePagination(pagination).limit
+            : undefined;
+        return { skip: Math.floor(offset), take };
+    }
+    if (!pagination) {
+        return {};
+    }
+    const normalized = normalizePagination(pagination);
+    return { skip: normalized.offset, take: normalized.limit };
+}
+function translateCondition(condition) {
+    if (!condition || typeof condition !== "object") {
+        throw new TypeError("Invalid query condition.");
+    }
+    validateFieldName(condition.field);
+    const { field, operator, value } = condition;
+    if (SIMPLE_OPERATORS.has(operator)) {
+        if ((operator === "in" || operator === "notIn") && !Array.isArray(value)) {
+            throw new TypeError(`Operator "${operator}" on field "${field}" requires an array value.`);
+        }
+        if ((operator === "contains" ||
+            operator === "startsWith" ||
+            operator === "endsWith") &&
+            typeof value !== "string") {
+            throw new TypeError(`Operator "${operator}" on field "${field}" requires a string value.`);
+        }
+        return { [field]: { [operator]: value } };
+    }
+    switch (operator) {
+        case "isNull":
+            return { [field]: { equals: null } };
+        case "isNotNull":
+            return { [field]: { not: null } };
+        case "like":
+            return { [field]: translatePattern(field, value) };
+        default:
+            break;
+    }
+    if (RELATION_OPERATORS.has(operator)) {
+        const nested = toPrismaWhere(value) ?? {};
+        return { [field]: { [operator]: nested } };
+    }
+    throw new TypeError(`Unsupported query operator "${String(operator)}" on field "${field}".`);
+}
+function translatePattern(field, value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError(`Operator "like" on field "${field}" requires a pattern.`);
+    }
+    const leading = value.startsWith("%");
+    const trailing = value.endsWith("%");
+    // The lookbehind pins the trailing match to the start of a `%` run; plain
+    // `%+$` retries from every `%` in an interior run, which is quadratic.
+    const inner = value.replace(/^%+/, "").replace(/(?<!%)%+$/, "");
+    if (inner.length === 0 || inner.includes("%") || inner.includes("_")) {
+        throw new TypeError(`Pattern "${value}" on field "${field}" is not supported; only leading/trailing % wildcards are allowed.`);
+    }
+    if (leading && trailing) {
+        return { contains: inner };
+    }
+    if (trailing) {
+        return { startsWith: inner };
+    }
+    if (leading) {
+        return { endsWith: inner };
+    }
+    return { equals: inner };
+}
+function validateFieldName(field) {
+    if (typeof field !== "string" ||
+        !FIELD_PATTERN.test(field) ||
+        FORBIDDEN_FIELDS.has(field)) {
+        throw new TypeError(`Invalid query field name "${String(field)}".`);
+    }
+}
+function isPlainObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}
+//# sourceMappingURL=queryBuilder.prisma.js.map

package/dist/queryBuilder/queryBuilder.type.d.ts

@@ -0,0 +1,48 @@
+import type { PaginationInput, SortInput } from "../databaseType/databaseType.type.js";
+import type { RelationInclude } from "../relations/relations.definition.js";
+export type { PaginationInput, QueryOptions, SortDirection, SortInput, } from "../databaseType/databaseType.type.js";
+/**
+ * Supported query operators.
+ *
+ * - `like` matches a SQL-style pattern using `%` wildcards at either end.
+ * - `some` / `every` / `none` apply a nested {@link QueryFilter} to a
+ *   collection relation; `is` / `isNot` apply one to a single relation.
+ */
+export type QueryOperator = "equals" | "not" | "in" | "notIn" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "like" | "isNull" | "isNotNull" | "some" | "every" | "none" | "is" | "isNot";
+/**
+ * Operators that take a nested filter targeting a relation.
+ */
+export type RelationOperator = "some" | "every" | "none" | "is" | "isNot";
+/**
+ * Generic filter condition.
+ */
+export interface QueryCondition {
+    readonly field: string;
+    readonly operator: QueryOperator;
+    readonly value?: unknown;
+}
+/**
+ * Generic logical filter.
+ */
+export interface QueryFilter {
+    readonly conditions?: readonly QueryCondition[];
+    readonly and?: readonly QueryFilter[];
+    readonly or?: readonly QueryFilter[];
+    readonly not?: QueryFilter;
+}
+/**
+ * Query builder state.
+ */
+export interface QueryBuilderState<TField extends string = string> {
+    readonly filter?: QueryFilter;
+    readonly pagination?: PaginationInput;
+    /**
+     * Explicit row offset. Takes precedence over `pagination.page` when both
+     * are present.
+     */
+    readonly offset?: number;
+    readonly sort?: readonly SortInput<TField>[];
+    readonly select?: readonly TField[];
+    readonly include?: readonly RelationInclude[];
+}
+//# sourceMappingURL=queryBuilder.type.d.ts.map

package/dist/relations/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Entity relation definitions and registry.
  */
-export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, isRelationType, isCollectionRelation, isSingleRelation, type RelationDefinition, type RelationType, type RelationLoadOptions, type RelationInclude, } from "./relations.definition.js";
+export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, type RelationDefinition, type RelationType, type RelationLoadOptions, type RelationInclude, type ToPrismaIncludeOptions, } from "./relations.definition.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/relations/index.js

@@ -3,5 +3,5 @@
  *
  * Entity relation definitions and registry.
  */
-export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, isRelationType, isCollectionRelation, isSingleRelation, } from "./relations.definition.js";
+export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, } from "./relations.definition.js";
 //# sourceMappingURL=index.js.map

package/dist/relations/relations.definition.d.ts

@@ -0,0 +1,184 @@
+import type { DatabaseOperationOptions } from "../databaseType/databaseType.type.js";
+/**
+ * Describes a relation between two database entities.
+ */
+export interface RelationDefinition<TParent = unknown, TChild = unknown> {
+    readonly name: string;
+    readonly parent: TParent;
+    readonly child: TChild;
+    readonly type: RelationType;
+    readonly foreignKey: string;
+    readonly referencedKey: string;
+    readonly nullable?: boolean;
+}
+/**
+ * Supported database relation types.
+ */
+export type RelationType = "one-to-one" | "one-to-many" | "many-to-one" | "many-to-many";
+/**
+ * Generic relation loading options.
+ */
+export interface RelationLoadOptions extends DatabaseOperationOptions {
+    /**
+     * When `false`, collection relations resolved through a registry are
+     * filtered to rows whose soft-delete field is null.
+     */
+    readonly includeDeleted?: boolean;
+    /**
+     * Maximum nesting depth allowed for includes (default 5).
+     */
+    readonly depth?: number;
+}
+/**
+ * Default maximum include depth.
+ */
+export declare const DEFAULT_INCLUDE_DEPTH = 5;
+/**
+ * Options for {@link toPrismaInclude}.
+ */
+export interface ToPrismaIncludeOptions {
+    /**
+     * Registry used to validate relation names and detect cycles. When
+     * supplied, `parent` identifies the root model.
+     */
+    readonly registry?: RelationRegistry;
+    /**
+     * The model the top-level includes belong to (required with `registry`).
+     */
+    readonly parent?: unknown;
+    /**
+     * Maximum nesting depth (default {@link DEFAULT_INCLUDE_DEPTH}).
+     */
+    readonly depth?: number;
+    /**
+     * When `false`, collection relations are filtered on `softDeleteField`.
+     */
+    readonly includeDeleted?: boolean;
+    /**
+     * Soft-delete column applied when `includeDeleted` is `false`
+     * (default `deletedAt`).
+     */
+    readonly softDeleteField?: string;
+}
+/**
+ * Describes a relation that can be included in a query.
+ */
+export interface RelationInclude {
+    readonly relation: string;
+    readonly select?: readonly string[];
+    readonly include?: readonly RelationInclude[];
+}
+/**
+ * Creates a one-to-one relation definition.
+ */
+export declare function oneToOne<TParent = unknown, TChild = unknown>(definition: Omit<RelationDefinition<TParent, TChild>, "type">): RelationDefinition<TParent, TChild>;
+/**
+ * Creates a one-to-many relation definition.
+ */
+export declare function oneToMany<TParent = unknown, TChild = unknown>(definition: Omit<RelationDefinition<TParent, TChild>, "type">): RelationDefinition<TParent, TChild>;
+/**
+ * Creates a many-to-one relation definition.
+ */
+export declare function manyToOne<TParent = unknown, TChild = unknown>(definition: Omit<RelationDefinition<TParent, TChild>, "type">): RelationDefinition<TParent, TChild>;
+/**
+ * Creates a many-to-many relation definition.
+ */
+export declare function manyToMany<TParent = unknown, TChild = unknown>(definition: Omit<RelationDefinition<TParent, TChild>, "type">): RelationDefinition<TParent, TChild>;
+/**
+ * Creates a relation include definition.
+ */
+export declare function includeRelation(relation: string, options?: {
+    readonly select?: readonly string[];
+    readonly include?: readonly RelationInclude[];
+}): RelationInclude;
+/**
+ * Validates a relation include (recursively).
+ */
+export declare function validateInclude(include: RelationInclude): void;
+/**
+ * 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 declare function toPrismaInclude(includes: readonly RelationInclude[], options?: ToPrismaIncludeOptions): Record<string, unknown>;
+/**
+ * Creates a nested relation include.
+ */
+export declare function includeRelations(...includes: readonly RelationInclude[]): readonly RelationInclude[];
+/**
+ * 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 declare class RelationRegistry {
+    private readonly relations;
+    /**
+     * Registers a relation.
+     */
+    register(relation: RelationDefinition): this;
+    /**
+     * Registers multiple relations.
+     */
+    registerMany(relations: readonly RelationDefinition[]): this;
+    /**
+     * Gets a relation by name.
+     *
+     * Without `parent` the name must be unique across all parents; an
+     * ambiguous lookup throws.
+     */
+    get(name: string, parent?: unknown): RelationDefinition | undefined;
+    /**
+     * Checks whether a relation exists.
+     */
+    has(name: string, parent?: unknown): boolean;
+    /**
+     * Removes a relation. Without `parent`, every relation with that name is
+     * removed.
+     */
+    remove(name: string, parent?: unknown): boolean;
+    /**
+     * Returns all registered relations.
+     */
+    all(): readonly RelationDefinition[];
+    /**
+     * Returns relations for a specific parent entity.
+     */
+    forParent(parent: unknown): readonly RelationDefinition[];
+    /**
+     * Returns relations for a specific child entity.
+     */
+    forChild(child: unknown): readonly RelationDefinition[];
+    /**
+     * Clears all registered relations.
+     */
+    clear(): void;
+    /**
+     * Returns the number of registered relations.
+     */
+    get size(): number;
+    private findByName;
+}
+/**
+ * Creates a relation registry.
+ */
+export declare function createRelationRegistry(relations?: readonly RelationDefinition[]): RelationRegistry;
+/**
+ * Validates a relation definition.
+ */
+export declare function validateRelation(relation: RelationDefinition): void;
+/**
+ * Checks whether a value is a supported relation type.
+ */
+export declare function isRelationType(value: unknown): value is RelationType;
+/**
+ * Returns whether the relation represents a collection.
+ */
+export declare function isCollectionRelation(relation: RelationDefinition): boolean;
+/**
+ * Returns whether the relation represents a single entity.
+ */
+export declare function isSingleRelation(relation: RelationDefinition): boolean;
+//# sourceMappingURL=relations.definition.d.ts.map